Curating forum posts

Destry · 2020-07-15 11:05:04

[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)

Bloke · 2020-07-15 11:35:12

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.

Destry · 2020-07-15 12:02:05

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:

The 1% of the community that actually understands the same things contributes more to the docs directly.
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.

etc · 2020-07-15 13:42:02

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?

Destry · 2020-07-15 15:22:42

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.

Bloke · 2020-07-15 15:39:21

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:

Your forum query is answered with a seriously cool bit of code that you think is of benefit to others.
You (preferably) or someone else (in retrospect) use the “Curate” link under the post that contains the code of wider benefit.
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).
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)

Destry · 2020-07-15 16:04:24

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)

Bloke · 2020-07-15 16:15:05

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.

Destry · 2020-07-15 16:26:23

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?

gaekwad · 2020-07-16 10:31:11

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

Bloke · 2020-07-16 10:47:44

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)

gaekwad · 2020-07-16 10:56:56

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.

gaekwad · 2020-07-16 11:01:30

Also, for all our sanity, it would be super amazing and great if we could use the time after 4.8.2 drops for more eyes on docs from more people. Destry went way above and beyond last winter and things have been fairly quiet since.

Clearly we have smart people here, what can we do to harness the smartness? Is it just a matter of finding interested people and then co-ordinating, or am I missing something obvious?

Bloke · 2020-07-16 11:28:41

I’ve put together some words recently, including some plugin stuff. And the installation/upgrade guides are pretty good now. We have at least one new admin callback to document after 4.8.2. Themes doc needs tweaking.

The main areas we need help are in writing a task-oriented admin guide. e.g. To do such-and-such, ensure pref xyz is on, and then do this, this and that. I expect a lot of this can be cadged and updated from the ‘individual panel docs’ that we have lurking around, then we can finally delete those and redirect.

The key here is to construct a single doc or segment that covers common admin-side concepts such as searching for stuff, sorting tables by clicking column headings, filtering out columns that aren’t currently the sort focus, pagination, multi-edit, and so forth. That can then be referenced from topic sections and saves repeating ourselves. Saves a lot of unnecessary wording in each topic.

Specific tasks can then be constructed that encompass these key elements inside the docs.textpattern.com/build/content-types doc. Things like:

Writing and publishing an article (which incorporates draft status, default publishing status, default section, custom fields and their creation, locating articles to edit, yahde yahde).
Categorising content and what it does for site visitors. This includes how to manage category trees.
Adding an image to an article (which incorporates the Images panel and possible mention of com_article_image as an enhanced workflow).
Creating lists of links.
Managing and using files.
Handling comments, spam, comment prefs, and how to wire them up for acceptance and display on articles (which touches on Forms in the next doc).

That covers the ‘content types’ doc in our new landing page.

Similarly, we need the docs.textpattern.com/build/site-structures doc that covers how to:

Create sections that mimic your intended content structure.
Build pages to support that, encouraging reuse.
Use forms to offload repetitive tasks (touch on shortcodes, perhaps with link to the shortcode examples).
What override forms mean in terms of diverting processing on an ad-hoc basis (this is also mentioned from the content doc in terms of how to use them).
Use styles to govern look and feel, and reuse across sections.
Mention themes, and link to the themes doc that Destry wrote.

One of the things putting me off doing the tags, btw, is the level of repetition due to limitations of GitHub’s Liquid implementation. I’d love to write some templates like I’ve done for the global tags and common presentational tags. Something we can just throw content at to render attribute lists and genealogy and examples and things like that, instead of typing the structures by hand each time.

It’d be great to have each tag doc as just a collection of variables that set up the content, and then these get thrown at templates to render. If you look at the work I’ve started in the section_list tag, for example, you’ll see that the entire common attributes and global attributes sections are rendered like this:

{% include atts-common.html break="" breakby="" %}
{% include atts-global.html class="tag name or unset" %}

That’s it. You can see that we include just two common attributes and of course the entire global set, customising the value of the ‘class’ attribute with something that isn’t the default. I’d like to do the same kind of thing with all attributes to cut down on repetition, plus template out the search results better. I think GitHub Liquid can do the former, so we might be able to make some inroads into that, but definitely not the latter as I’ve tried it and failed (plus the following 16 commits from that point where I was testing it).

The global/common atts needs rolling out to all tag docs, removing any of the manually-written attributes that coincide with those. And I figure while doing that we might as well write a template to govern an individual attribute. Something that takes arguments like name/value (or value set as an array), a description of each value, plus the default.

I’m hoping if we move to locally-hosted docs that we’ll have more control over this and can add support for a better Liquid engine.

Last edited by Bloke (2020-07-16 11:47:10)

colak · 2020-07-16 15:51:51

I think that we should prompt people to be adding their examples to txp.tips. I have done that a few times but there were no submissions as far as I know.

Textpattern CMS

Textpattern CMS support forum

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