Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: Docs site refresh effort
I’m in.
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
Re: Docs site refresh effort
I’ve been thinking about the content of the docs site recently, and how we have a wealth of information stored in this forum, including code snippets, tips, tricks, and similar things.
Yep. Lots of useful bits and bobs but not well organized or visible.
one idea I have been considering is having a one-docs-page-per-week focus, and inviting anyone with snippets, tips, tricks or similar things to collaborate on the editing process. We can add examples, explanatory text, things to avoid, recommendations, that sort of thing.
This collaborative focus on a given doc might work well when it comes time to actually shuffle words around on a page.
But — and I don’t mean to step on toes — I’d advise mapping out a plan before getting to that point or it could be a lot of wheel spinning.
Following is one approach to consider to get everyone in sync.
What is the overall Goal?
We know the docs are moving off github, and they’re going to stay as Jekyll pages, just not hampered by github constraints. Good. That saves a lot of markup work, styles development, etc. I would also suggest keeping with Markdown since that’s all done.
Stef has ideas for more dynamic handling of tag data. He’s probably the only one that does, so he can be in charge of that. ;) Pete, you’ll know what to do with platform setup. And Phil will be on hand if any new style work needs decided on, but that seems pretty covered to me. So far so good.
So what does need changed that can shed light on the main goal? That’s the question to answer here.
Is it the information architecture? Yes, partly. Last time we were at this junction, there was an effort to merge doc pages into more complete tutorials, while at the same time eliminate needless dead weight, such as admin-side panel pages that only explained the obvious. I think we were all on board with this, and the repo was working well to keep track of the consolidation effort and the resulting file tree changes. I recommend keeping on in that direction since a lot of ground was made.
Is it page level editing? Yes, again. Evident by the IA changes, necessarily. So this begs another question: what are the needed edits?
Now we start to merge two objectives into our overall goal. One objective is the consolidation of material into single-page tutorials, as mentioned previously, expectedly longer pages with contents lists and opening summary paragraphs being the norm. (The themes doc is probably a good example of a page too long, maybe. TBD.)
The other objective is what Pete is aiming for in this thread; finding and extracting all the useful intel in this forum that should be in docs but is not, then working that in as part of the docs changes.
This demands a process for the hunting/mapping. Let’s call it workflow.
Workflow
First, lets not waste what tools the repo already provides for collaboration, communication, and controlled editing. We can still take advantage of that to revise docs where they are and move a largely completed site to the new platform later.
What needs added with the second objective in mind is a way to map the forum tidbits to the respective pages they are deemed suited to go. If we remember the collab effort being developed in the repo, where every doc page has its own dedicated issue, then we can easily use those issues as a convenient way to bridge doc pages with forum links. Any forum bit that seemingly relates with a given doc, add that link to the issue thread with a brief comment why it could be worth considering.
If collaborators don’t want repo accounts for the ongoing link gathering/mapping phase, then, as Pete suggested, an associated goog doc could be created for each repo issue, too, where people can add forum links. Repo editors can then transfer that to issue threads.
This mapping, and the associated forum hunting/gathering of links is an important phase. It will greatly help keep the collaboration organized and moving forward.
Editing
Eventually, you’ll start seeing where the hunting/gathering phase for some topics/pages is exhausted and the actual developmental editing of a given page can begin. This will involve:
- following up with gathered forum links per doc and extracting the valued info from the associated forum posts/threads.
- organizing all the extracted info into a logical document flow
- edit, revise, repeat generously.
- use issue assignment protocols to edit between doc versions so no one steps on toes
What we might discover in the course of this work is the need for new doc pages or changes to the existing file tree. That’s fine, if so. It’s expected that we would by fact we’re fortifying docs with more information.
Does this make sense? The point is to not abandon what already works, or is a good idea, or can greatly facilitate the effort before it’s even necessary to move the installation.
Offline
Re: Docs site refresh effort
Word.
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
Re: Docs site refresh effort
A different workflow will need conceived in the future, though, assuming docs won’t be under versioning at that point. Docs and editing are like code — a never-ending process.
Offline
Re: Docs site refresh effort
For people who want to help but don’t have the history with Txp docs dev/editing as some of us do, and might be confused or inhibited by the aforementioned github workflow, a good and important way to dive in immediately with this effort is:
- start identifying topics that are seemingly missing in docs and are deemed needed, and make a list of those topics
- make sublists for those topics that provide links to forum threads or individual posts having answers or relevant explanations that would help draft the needed doc
- make those lists publicly available so collaborators can see them.
Only focus on topics that have core Textpattern solutions, not those relying on plugins.
Don’t worry about actually drafting docs until we get a fair number of such topics identified and supported by forum material, and then prioritized for development. Drafting and editing will come later in context of repo and versioning, and editors will help with suggestions about where info might go in the file tree.
Also, no topic is too simple. The bar on this is low. For example, how to add a logo is a common question new users have, and repeatedly asked/answered in the forum. Our goal will be to identify those topics, write docs for them (or work the info into suitable existing docs), and point people to a relevant doc in the future if a person doesn’t already find it self-sufficiently.
In fact, that should be your audience perspective when making topic lists — new users of Textpattern. As well any questions you might have of your own and not addressed anywhere in docs.
Once we seemingly exhaust identifying missing topics, we can turn more collective focus to identifying forum threads and posts (better) that hold valuable information for augmenting existing doc pages. That’s also a critical part of the overall goal.
Last edited by Destry (2020-12-02 10:07:10)
Offline
Re: Docs site refresh effort
Destry – thank you – agree with you 100%.
Offline
Re: Docs site refresh effort
Cool. We have a way forward.
Last edited by Destry (2020-12-02 10:00:12)
Offline
Re: Docs site refresh effort
Another way to identify topics is come up with better tag examples in tag pages. A lot of existing examples are either too generic or relying solely on the markup to make them clear, which of course they are not without accompanying context and explanation. Examples that reflect a variety of real use cases in the wild are best, from simple to more complex (such as extended attributes and related logic).
Offline
Re: Docs site refresh effort
For the editors and others concerned, we might want to keep an eye for impressions of docs as ‘crappiest’ and evaluate how such docs can be revised.
But don’t take every critique too literally, especially from any supposed authority who can’t spell WordPress and Textpattern correctly.
Others, including perhaps those for which English is a second language, might find the same elaborated material ‘excellent’, as our confrère Pat64 has.
Still, there is always room for improvement, and especially a big doc like the themes doc.
Last edited by Destry (2020-12-02 21:59:27)
Offline
#22 2020-12-02 16:27:58
- WebmistressM
- Member
- Registered: 2011-08-12
- Posts: 61
Re: Docs site refresh effort
1. start identifying topics that are seemingly missing in docs and are deemed needed, and make a list of those topics
So, are you saying that the Github version of the documentation is what we should look at solely? Was curious how the updates to github work when it comes to showing up on the docs.textpattern.com (whether it updates with every approved change on github)
Followed the contribution link to this readme: https://github.com/textpattern/textpattern.github.io/blob/master/README.md … but ran into a broken link for the “documentation collaboration procedures”
Last edited by WebmistressM (2020-12-02 16:37:15)
Offline
Re: Docs site refresh effort
WebmistressM wrote #327208:
So, are you saying that the Github version of the documentation is what we should look at solely (instead of the Docs section here: https://docs.textpattern.com/)?
They are the same thing. The documentation is maintained / modified in GitHub and published to docs.textpattern.com automatically.
Offline
Re: Docs site refresh effort
Destry wrote #327202:
But don’t take every critique too literally, especially from any supposed authority who can’t spell WordPress and Textpattern correctly.
This. Ditto for anyone SERPs spearfishing for Textpattern-mention clickbait drivel.
Offline