Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#11 2020-12-06 16:40:04

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,662
Website

Re: Topic Suggestions for User Documentation

Bloke wrote #327294:

I quite like the Ghost topic subdivision there.

Maybe we need to pause and reflect on what kind of top-level organization is wanted/needed on the surface, even if superficially, so to guide how we should merge in any new topic ideas.

If we compare Ghost’s docs homepage with Txp’s currently, and what was slated, there’s not a lot of difference in structure, really, just respective types and presentation.

Ghost docs Current Txp docs Slated Txp docs Comments
Core Concepts Marketing info, apparently
Install / Setup Installation handling Setup and Configuration Slated is more or less the same as ghost in scope
Theme Documentation Themes Construction and Presentation Slated aims to consolidate build topics
API Reference Development Construction and Presentation Slated aims to consolidate build topics
FAQ Tutorials and FAQs Slated aims to fade out FAQ factoids by working info into full tutorial-like docs
Migration Guides Used to be in old wiki; never kept current.
Tags Tags and Attributes !

I would leave marketing info to the main website, as already mentioned earlier in this thread.

As it stands, there’s only two Txp docs on themes. Does that require a separate list in the homepage? Questionable. Which is why slated aimed to merge design and development topics into Construction and Presentation (i.e. build topics).

I don’t know if API and plugin development is really the same thing, but maybe it gets to more or less the same kinds of ideas and extended functionality. But does that require a separate list in the homepage? Again, not so sure, especially as in our case there is a single process like doc for plugin dev that links out to the other supporting pages. Thus only the initial process doc needs headlined.

I’ve argued in the past that when the Themes and Plugins sites were up, it might be logical to have their related documentation in those sites, in context with the actual themes and plugins content, respectively. Probably easier for people to find that way, too. Alternatively, and perhaps easier for docs editors, is to at least add links in the tops of those resource sites to their relevant headline docs so it’s all in context visually, if not physically.

FAQs… hopefully we didn’t forget that those were out of control once upon a time and we decided to write that kind of information into other docs in context of their topics, somewhat like what we’re trying to do now with bits and bobs of information scattered throughout the forum.

Migration guides, we had them in the old wiki for a few other CMSes, but the importing was always very fiddly, as often reported back, and the docs were never maintained against the evolution of CMSes on either side.

Regarding the notion of ‘tutorials’, the slated idea was to merge scattered little docs and ideas into more holistic docs around a given objective with Textpattern. Again using the Themes doc as an example. Other such subjects are Issued for development too, as the slated index shows.

Dos’s idea for a basic blog tutorial might be another example, as suggested, though it seems to me the default install of Txp is already a nice working blog. So maybe the goal there is to describe/unpack the default blog construction so people better understand it, as another way of approaching such a tutorial. Whatever the case, building website type X tutorials would equally cover construction and presentation, I would imagine, thus be documents suitably listed under slated’s Construction and Presentation region.

The only thing I see radically different between Ghost and Txp is more presentational box-work design around Ghost subjects. I would admit the current walls of blue links in the Txp docs index are a tad eye-straining. Maybe all they need is some disc bullets, or something, and to wrap the parenthetical bits under the links. That would probably be just enough to break it up effectively without much work.

Anyway, some perspective on history. Whatever people feel strongly about, as it pertains to designing a main index page, now is probably the time to share it so a consensual heading can be plotted.

Last edited by Destry (2020-12-06 16:49:02)

Offline

#12 2020-12-06 18:19:20

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 9,994
Website

Re: Topic Suggestions for User Documentation

I’m not saying that the Ghost docs were vastly different to ours, just that I liked the separation. Agree we have a lot of that already.

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 plugins site could house all the api (callback) stuff and how to write a plugin info, etc. 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.

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.

Tutorials, likewise. A link out to TxpTips perhaps and have that content take over? Not sure of the scope, but Jools is best placed to field this as he’s retooling the site.

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.


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

#13 2020-12-07 00:36:41

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,662
Website

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

#14 2020-12-07 01:00:57

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 9,994
Website

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

Online

#15 2020-12-07 07:05:31

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,662
Website

Re: Topic Suggestions for User Documentation

Which could mean the slated docs index page is already on the right track?

Offline

#16 2020-12-07 08:00:34

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,662
Website

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:

  1. Explain how the default them works (building blocks)
  2. 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
  3. 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

#17 2020-12-07 08:25:38

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 9,994
Website

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

Online

#18 2020-12-07 08:43:49

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,662
Website

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

Board footer

Powered by FluxBB