Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
#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.
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.
Txp Builders – finely-crafted code, design and Txp
Offline
Re: Docs site refresh effort
The procedures doc was a year past due, so if anything, an apology on my part. I can see where it needs another editing pass for tightening. I’ll do that in the next days.
I think it also needs a section that more clearly/directly addresses the consideration and action required at going from a topic idea to a repo issue, and how that may require additional thought/action toward the IA of the docs file tree.
For example, it seems like a lot of how to topics could arise from this latest effort, and the IA is not currently setup for that kind of single-focus documentation. Might have to think about that.
Last edited by Destry (2020-12-05 16:40:24)
Offline
Re: Docs site refresh effort
On a related note, I’d like to point out this from the Support section of .com/about/ is a good and well-structured message in relation to the collaboration goal outlined in the collaboration doc. / thumb up /
Textpattern CMS has extensive user documentation available, but if you cannot find what you are looking for in the documentation then the forum is the place to visit.
The paragraph that follows that quoted text, however, is a tad over-basting and mis-directed, imo. I’d turn focus there from ‘forum’ to community since the forum does not by itself define the Txp community.
Any marketing as far as the Forum goes only needs to communicate its friendly watering hole nature, and be done. Notions of help should be handled more like ‘If you can’t find what you need in User Docs, ask us in the forum and we’ll get you sorted.’
This section from the software’s repo ReadMe is a little out of sink with the desired help goal, as well…
Help and support
The Textpattern support forum is home to a friendly and helpful community of Textpattern users and experts. Textpattern also has a social network presence on Twitter.
There’s no mention of docs in relation to help, and it’s twisty on the forum vs. community focus actually, it’s probably okay there.
It might be prudent to audit the marketing and directional blurbs across platforms/resources and harmonize messaging; and as far as they concern help resources, ensure the user journey is first to docs and then to forum, if necessary.
Good opp there to plug the Txp Mastodon account, too, since Twitter is mentioned, and get a Masto logo/link in the network footer.
Last edited by Destry (2020-12-05 17:04:20)
Offline
#33 2020-12-05 22:01:57
- WebmistressM
- Member
- Registered: 2011-08-12
- Posts: 61
Re: Docs site refresh effort
Destry wrote #327286:
….. I think it also needs a section that more clearly/directly addresses the consideration and action required at going from a topic idea to a repo issue, and how that may require additional thought/action toward the IA of the docs file tree.
For example, it seems like a lot of how to topics could arise from this latest effort, and the IA is not currently setup for that kind of single-focus documentation. Might have to think about that.
Would you be talking about things like taxonomy, or how nesting (section > sub-section > Level 3 > …) works? I know that when it comes to “How to”/Tutorial style docs, it would seem that a single tutorial can have areas of its content which would allow organic introduction (through an internal link) to other tutorials or information sections of the overall Documentation. Is that the challenge (pain point) that you are talking about?
Offline
Re: Docs site refresh effort
Good question, mistress.
What you describe there is certainly one good idea for handling documentation growth and addressing discrete topics when it’s not sufficient or appropriate to elaborate on them in the course of a bigger doc (or one having a broader subject scope). We will keep that in mind, and probably use it.
Take the principle themes doc, for example, which is probably one of the largest docs in the tree at this point. It’s rather like a one-stop shop for learning about Txp themes functionality, and it covers quite a lot of ground. (I’m not sure we should continue with using images in docs, because it’s a shitload of tedious work that I don’t intend on subjecting myself to, but maybe some docs might be the exception.) Nevertheless, there could be theme subtopics identified later that sprout off (and link from) that doc in context of a given subject, both to address the subtopic more thoroughly and to help keep the ‘mother doc’ at about the max length/size we might want any given doc to be. That’s just speculation here.
At any rate, it is all elemental IA jostling (we can probably manage the tree any way we like once out of GitHub), and definitely part of what I’m talking about, yes. But there are other aspects of coordinating it, like:
- knowing what topics might be broken out (the listing phase were at now to assess it)
- from where in the tree should topics be broken out at (part of the assessing)
- if the docs tree needs directory changes to accommodate new topics, and what the best way for it is (vs. just new pages added)
- if any existing URLs will be changed (implying redirects needing taken care of)
- who will do what particular changes to the tree (likely those with write access to repo)
- who will write/edit docs (could be anyone who can follow the guidelines and open issues)
In other words, it’s not the most easy section of the collaboration doc to write in advance. We might not try to say everything, rather let some things play out organically through collaboration and the repo Issues.
Last edited by Destry (2020-12-06 16:57:02)
Offline
Re: Docs site refresh effort
Did I do good, boss? Did I? :)
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
Offline
Offline