Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: Topic Suggestions for User Documentation
I forgot to point out I was addressing all readers in that last post, not really replying to Bloke directly. Was just using you, Bloke, as a way to bring everyone’s focus on the topic of homepage organization.
But now that we’re whittling at it…
Bloke wrote #327300:
Plugin and theme docs on the relevant sites, in context: yes! With links out from the main docs site for people who go there first expecting to find them. . . . The only issue is that it’s currently all written in Markdown. So we either convert it (again!) to Textile… Nooooooo… or install the Markdown plugin there.
I vote for keeping it as simple as possible, which is probably leaving docs where they are and adding links to them from the respective resource sites. Same difference on the surface. But whatever Team Txp decides on physical storage is fine with me. (I know, I flip-flopped.)
No to FAQs unless they’re simply a short list of links to subtopics in other places, regarding really common things like tag traces and how to reset passwords.
Agree. And thanks for reminding me about the tag trace doc. ;)
Tutorials, likewise. A link out to TxpTips perhaps and have that content take over?
I guess it just depends on what the scope and size of a topic is and what the terms ‘tutorial and ‘how to’ mean to people. What would you call the theme’s doc, for example? I’m honestly not sure. A mini-manual?
Maybe we need to drop those kinds of terms on Txp’s side (tutorial , how to, faq…), and just call everything a ‘doc’ regardless of it’s size or nature. That’s what they are when it comes down to it, documentation. Just a thought.
I can live without migration guides. If and when we’re in a stronger position to offer assistance here by way of core/plugin functionality we can revisit.
I didn’t mean to sound discouraging, only that we used to have them and then decided their value was questionable. But yeah, that’s another bridge for later, I guess.
Offline
Re: Topic Suggestions for User Documentation
Destry wrote #327306:
I vote for keeping it as simple as possible, which is probably leaving docs where they are and adding links to them from the respective resource sites. Same difference on the surface.
Yeah, that’s a better approach! If it ain’t broke… :)
Maybe we need to drop those kinds of terms on Txp’s side (tutorial , how to, faq…), and just call everything a ‘doc’ regardless of it’s size or nature.
That’s worthy of consideration. With the focus shift to more topic-based content rather than functionality-based content, the lines between a tutorial and a manual become blurred. People learn new stuff by following goal-oriented documentation, which is part tutorial, part user guide, part how-to.
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: Topic Suggestions for User Documentation
Which could mean the slated docs index page is already on the right track?
Offline
Re: Topic Suggestions for User Documentation
Is there a descriptive breakdown of the default theme’s templates anywhere that could be used as reference in writing a walkthrough of building a blog?
It’s repo offers this bit of contemplation, strong text added here:
It is intended as a starting point for new users learning the Textpattern CMS for the first time or existing users that want to adapt their current code for modern standards, and is not intended as a finished production theme . . .
Following on with dos’s suggestion, I think a full goal-oriented doc to build a blog theme is a good idea.
I would add that the approach would be to unpack the default theme, explain how it’s structured with templates and tags, and how it might be modified to an owners liking/need, while still functioning properly in relation to themes management.
This would be a big doc, I suspect, like the themes doc, and would help people in three ways:
- Explain how the default them works (building blocks)
- Explain where/how common things can be modified while keeping to a blog type genre (e.g. changing the logo, adding a tag cloud, adding a date-based archive…), or how to tweak areas more toward a photoblog, vlog, etc
- Demonstrate the connection with themes development and management
Note how a more goal-oriented doc like this can merge in and address other topic ideas identified (e.g. add a logo) in a more holistic way. That is good.
A doc like this would easily sit under Construction and Presentation.
And it might be the only such site genre doc needed for explaining how to build sites with Txp because the modification concepts are the same regardless of what type of site genre one wants.
Offline
Re: Topic Suggestions for User Documentation
Destry wrote #327310:
Is there a descriptive breakdown of the default theme’s templates anywhere
In Phil’s head :)
But seriously, the theme itself is heavily commented so bringing those comments out and expanding on them to explaining the building blocks behind the theme is worthwhile. Might also lead to further honing a few comments in the theme code itself.
Note how a more goal-oriented doc like this can merge in and address other topic ideas identified (e.g. add a logo) in a more holistic way.
Yes, that’s fab.
Which could mean the slated docs index page is already on the right track?
Yep. I like the new structure.
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: Topic Suggestions for User Documentation
Bloke wrote #327313:
the theme itself is heavily commented
Yep, just wanted to make sure I wasn’t missing something else.
Cool. I think this is a docs Issue ready to be made, and as such can be made (and used as descriptive example of workflow in the collaboration doc). I’ll take it that far, but leave the issue un-assigned.
Offline