Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#1 2020-07-15 11:05:04

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

Curating forum posts

[Topic split from forum.textpattern.com/viewtopic.php?id=50892

activecats shortcode.

One for the shortcode examples list? This kind of knowledge just gets lost in these middles of threads of no indicative heading.

Sometimes I might step up on the initiative of transferring these ill-planted fruits, but the knowledge, as in this case, is often above my ability to describe suitably/accurately for documentation (i.e. I often need the documentation to grok the solution), which is why I don’t touch tag examples, for example. And remember what a slog it was for the themes doc, still unfinished for the foreseeable future.

While the five or so people that regularly hang out in the forum are as oriented to it as android librarians, and thank goodness for it, most newcomers will try to be self-sufficient first via user documentation. This is evident by the repeated proclamations of new names in the boards saying things like ‘I tried to find it in the documentation first but the answer isn’t there’. Evidence of precious time wasted. So they are inevitably forced to the forum to make such procs because of the disjunct between the on-the-fly / off-the-cuff knowledge bombs dropped here and the vetted/archived knowledge there where it’s first expected to be found by nature of being ‘user documentation’.

It changes nothing about providing forum help; if anything, it improves it. One simply writes the doc there, instead of here, then provides a link from here to there. Information single-sourcing at its best. Up is right and back is over.

Old problem, old gripe, from old Destry. Carry on.

Last edited by Destry (2020-07-15 16:08:12)

Offline

#2 2020-07-15 11:35:12

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,250
Website GitHub

Re: Curating forum posts

Good point, well made. If ever I post a how-to or some example that has wider applicability, I’ll endeavour to add it to the docs first and then link from the forum rather than add it directly in the forum.


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Online

#3 2020-07-15 12:02:05

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

Re: Curating forum posts

It’s a tough act, I know. What it often means is the devs — who know how stuff works — must be the first to explain it. But this also puts more burden on their already large contributions to the project.

So the only solutions are, seemingly, after first letting devs put docs wherever the hell they want, is:

  1. The 1% of the community that actually understands the same things contributes more to the docs directly.
  2. The same 1% ports the dev fruits from point A to point B after the fact.

There’s never an all-around win in open source documentation.

Offline

#4 2020-07-15 13:42:02

etc
Developer
Registered: 2010-11-11
Posts: 5,028
Website GitHub

Re: Curating forum posts

Destry wrote #324545:

the devs — who know how stuff works — must be the first to explain it. But this also puts more burden on their already large contributions to the project.

Dev or not, finding/testing a nice solution (though enjoyable) often takes time.. sometimes to discover that the problem does not interest anyone any more.

Wouldn’t it be loverly if the question authors contributed to the docs?

Offline

#5 2020-07-15 15:22:42

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

Re: Curating forum posts

etc wrote #324550:

finding/testing a nice solution

That’s a good point. And the forum is good for that kicking the tires.

Wouldn’t it be loverly if the question authors contributed to the docs?

You mean when someone’s question has been answered here, wouldn’t it be nice if they then took the time to contribute the reasoned response to the docs? Yes, that would be loverly indeed.

That presumes a more UGC type of docs platform, though, which makes Tips a more attractive place.

Offline

#6 2020-07-15 15:39:21

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,250
Website GitHub

Re: Curating forum posts

Destry wrote #324551:

That presumes a more UGC type of docs platform, though

We’re currently assessing the feasibility of moving the docs in-house. Trialling it now. Changes will still be governed by a repo and git though, so the usual barriers to entry apply (i.e. an account is required).

So I wonder if there’s a simple way to add a button to forum posts, similar to ‘report’ that could send off a request to a central location? Or even directly as an issue to the git docs repo via an API? Just some button that community people can use to bring a forum post to attention and suggest it for inclusion in the docs.

I’m not sure of the forum capabilities here, but I can imagine the process being:

  1. Your forum query is answered with a seriously cool bit of code that you think is of benefit to others.
  2. You (preferably) or someone else (in retrospect) use the “Curate” link under the post that contains the code of wider benefit.
  3. You see a form where you enter a title and a brief summary of why you’re suggesting this post. e.g. where you think it fits (tag page, installation, theme, etc).
  4. You hit ‘Submit’ and the link to the post (along with your forum username and reason for suggestion) is fired off to somewhere we can all access. Perhaps a central mailbox (worst case, as it’s a closed shop). A git issue is better as it means anyone can pick an issue up and run with it. Not sure if the API can auto-complete forms on behalf of someone else, like an ‘issue robot’.

Once that’s lodged we have a record of the suggestion, a link to the forum of the curated info and, ultimately, an issue that tracks its resolution and folding into the docs. Not sure how we’d cater for duplicate suggestions. Maybe a filter can run on insertion of the Issue to check the URL hasn’t already been handled/suggested?

That’d be pretty sweet. I wonder if it’s possible with some code glue.

EDIT: a poor-man’s version of the above might be a Curate link that goes directly to the git repo. i.e. when you click the link, you end up in the New Issue form, with it having pre-selected the ‘Suggestion’ template and, perhaps if the API allows it, to pass in the ‘subject’ (post URL) from the GET params. Worst case scenario right now with the docs hosted on GitHub: you’re asked to sign up, then taken to the New Issue . If you; logged in, you’ll get taken straight there, write the issue up and submit it. Whether this process changes/becomes simpler when we self host the docs, I’m not sure.

Last edited by Bloke (2020-07-15 15:51:11)


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Online

#7 2020-07-15 16:04:24

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

Re: Curating forum posts

Bloke wrote #324553:

some button that community people can use to bring a forum post to attention and suggest it for inclusion in the docs . . . That’d be pretty sweet.

That’s an excellent idea! Just having a queue of links to follow up with is half the battle to knowing what to write for those who can/will (a different kind of problem). That at least takes the burden out of knowing where to look. And it gets direct feedback from users about what is actually worth writing about.

In fact, that is an interesting notion too… having some way for users to see the reported list and allow them to up-vote on items in it as a way to prioritize what gets done first. Maybe that’s too ambitious and hopeful, for this drowsy bunch, though.

Last edited by Destry (2020-07-15 16:24:50)

Offline

#8 2020-07-15 16:15:05

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,250
Website GitHub

Re: Curating forum posts

Okay, so let’s see what capabilities the forum has for adding custom stuff. That’s above my pay grade right now so I might have to defer to Phil or Pete on this.

But if there’s a way to hack the forum to do it, and we can find a sensible way to receive and catalogue curation notifications (an issue queue would be my go-to as it’s public) then I’ll help out with code in any way I can to facilitate this.


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Online

#9 2020-07-15 16:26:23

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

Re: Curating forum posts

If there was a thread about how to use Prism, I would upvote that for a starter. What, some lines in the page header, or something?

Offline

#10 2020-07-16 10:31:11

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,134
GitHub

Re: Curating forum posts

Bloke wrote #324553:

So I wonder if there’s a simple way to add a button to forum posts, similar to ‘report’ that could send off a request to a central location? Or even directly as an issue to the git docs repo via an API? Just some button that community people can use to bring a forum post to attention and suggest it for inclusion in the docs.

Further reading

Offline

#11 2020-07-16 10:47:44

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,250
Website GitHub

Re: Curating forum posts

Nice find!

I think that makes it super simple then. All we need to do is locate the code in FluxBB that handles adding Report | Delete | Edit | Quote beneath a post and add one extra link to the GitHub docs site, passing forward:

  • the template to use (one we’ll add to the set).
  • the link to the post as body content, perhaps (unless that obliterates the template). Or title.
  • a title prefix to help us sort the issues irrespective of label. e.g. [Curation request]:.
  • a label (for-review or something that indicates its recently-added status). We’ll change this as and when the request is accepted and folded into the docs.

Anything I’ve missed above that’d help us manage this?

If anyone doesn’t have a GitHub account, they’ll be prompted to sign in/up when they click the link. Hopefully the passed params will survive the login process.

Game on.

So who’s good with FluxBB? Is this a mod or a plugin? I’d hope plugin so it makes upgrades simpler in future. Given an example plugin we have already employed, plus trawling FluxBB docs for reference, I expect can throw some code together to do this, unless someone else fancies doing it.

Last edited by Bloke (2020-07-16 10:50:00)


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Online

#12 2020-07-16 10:56:56

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,134
GitHub

Re: Curating forum posts

For this to work, we’re gonna need some docs triage people – and authors, tweakers (ahem), editors, and the like. I’m glass half full but please let’s not go into this blind.

Offline

Board footer

Powered by FluxBB