Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
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
#25 2020-12-02 16:38:11
- WebmistressM
- Member
- Registered: 2011-08-12
- Posts: 61
Re: Docs site refresh effort
gaekwad wrote #327209:
They are the same thing. The documentation is maintained / modified in GitHub and published to docs.textpattern.com automatically.
Okay. 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”
Offline
Re: Docs site refresh effort
WebmistressM wrote #327211:
ran into a broken link for the “documentation collaboration procedures”
We haven’t finished that doc yet so it’s currently hidden (draft). The next link down gives the current guidelines:
docs.textpattern.com/brand/user-docs-guide
Sorry for the hassle.
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Hire Txp Builders – finely-crafted code, design and Txp
Offline
Re: Docs site refresh effort
Bloke wrote #327219:
We haven’t finished that doc yet so it’s currently hidden (draft).
Sorry for the hassle.
I will try to provide the collab procedures doc in the next days.
Not long ago I thought it probably wasn’t necessary, but with this recent look at docs again, to pull from the forum, and the hope and potential for more contributors, I can see it will be useful to at least explain the unique way were using the repo’s Issues and Labels.
I’ll be as brief with it as I can.
Offline
Re: Docs site refresh effort
For what it’s worth to you, this is a great example of the end game of this effort.
- A doc already exists waiting to be discovered and used by some self-sufficient type.
- Maybe they don’t actually look for it, or missed it in the effort. They ask about their problem in the forum.
- A knowledgeable gentleperson briefly replies with a smile and provides the link to the appropriate fiche in the intelligence bureau.
- (Intelligence agents consider how to improve organization of the bureau’s files.)
Done-dittly-did!
Future hunters of subject either find the doc or the forum thread and see the direct link… All roads lead to the done house. People get back to their primary tasks faster. It’s a wonderful thing.
So, if you know a doc exists and answers someone’s question posed in the boards, don’t waste your time waxing redundant to them, just give them the dope link. Then wait and see what happens. If the Team Txp and community teamwork is good, nothing more will happen and the forum is one tiny step closer to being less bloated and more efficient. Utopia.
That is the goal of this current docs siege.
Last edited by Destry (2020-12-03 17:37:20)
Offline
Re: Docs site refresh effort
Okay, here is a rough pass on the docs collaboration procedures. It’s really just what has been relayed in this thread already, but ties in the repo elements a bit. It has gaps, undoubtedly, leaving hanging questions, so please let me know what those might be. :) It might all be obsolete when the tree’s replanted. I don’t know.
Correct urls to it wherever needed, though I doubt anyone has that one bookmarked.
Yes, the top-level Txp style guide link from the ReadMe file in the docs repo was/is 404, too, and may remain so indefinitely. 16 years without one so far, there’s probably no rush, or real need. We’ll have to see how it goes. Anyone with experience putting one of those together… be my guest. Writing style guides burns me fast.
Last edited by Destry (2020-12-04 15:22:26)
Offline
Re: Docs site refresh effort
That is grand. Thanks, Destry.
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Hire Txp Builders – finely-crafted code, design and Txp
Offline