Topic Suggestions for User Documentation

Destry · 2020-12-03 14:32:41

Following on with the collective focus to augment user docs with forum intelligence, and with respect to:

Let’s start identifying topic ideas here to get the mossy rock rolling and for lack of a more visible location. Reply with any doc topics you think are missing in user docs, no matter how simple it may seem. We (you docs editors with forum mod rights) should help me keep this head post up-to-date with suggestions.

Only topic ideas and concise discussion on them here, please. If you have any questions about this effort, read the collaboration procedures first. If you still have questions, post them in this other thread.

To anyone who has ever complained about Txp user docs, this is your moment to shine.

Installation and Configuration

Auto-installation

(Your suggestions here!)

Construction and Presentation

Building the perfect blog, includes subtopics like adding a logo, etc, or tweaking to a photoblog, and so on.
Adding a splash page

(Your suggestions here!)

Tags and Attributes

(Your suggestions here!)

External Topics

browser options (Adminer / phpMyAdmin etc)
desktop apps (Sequel Pro etc)
useful command-line interface tips

(Your suggestions here!)

Last edited by Destry (2020-12-07 08:21:30)

Bloke · 2020-12-03 18:52:06

Although possibly of wider scope, one of the questions we do see from time to time is Can Textpattern be used for such-and-such a site? and I’m never sure whether this is marketing (.com) or documentation, or if it somehow falls between the cracks.

While we don’t want to list every potential use, it would be good not only for SERPS but also to point people who ask this question at a resource that explains what Txp can do out of the box and what it can do with a plugin or two.

Saying it can make “any kind of site” is useless because nobody is looking to build an “any” site. In the same vein as you don’t tend to hire the labourer who can do “any job” or “no job too small”. People are looking for the specialist to install their bathroom or kitchen or plumbing or hang doors.

So if we had somewhere that said Txp can do intranets, blogs, portfolios, company sites, municipal sites, photography showcase sites, travel sites, community login sites (with a plugin or two), blah blah then we’ll a) have some good search engine fodder for specific terms and b) be able to point anyone at this resource to likely answer their question.

As I say, it’s part marketing, part information so maybe it doesn’t belong on the docs site. But then again, maybe it does.

If it doesn’t, where should we put such a thing?

zero · 2020-12-03 21:37:22

Bloke wrote #327244:

If it doesn’t, where should we put such a thing?

On the Textpattern.com home page — site showcase – Textpattern can do: intranets – example, blogs – example, portfolios – example, company sites – example, municipal sites – example, photography – example. showcase sites – example, travel sites – example, community login sites – example (with a plugin or two), blah blah – example.

just my 2p

Bloke · 2020-12-03 22:05:30

zero wrote #327254:

On the Textpattern.com home page

Yeah, that would make perfect sense. I did have that same thought a short while after I posted, but didn’t get a chance to revoke my post (dinner time, blah blah).

Let’s consider categorising the showcases in some meaningful way, and offer some links in the accompanying intro text that list the ‘types’ of sites that these represent. An obvious solution is a category list that would take you to a page that shows only those types of site, filtered from the entire set. That makes a nice landing page for anyone who wants to point anyone who asks in the forum to a particular genre.

I concur it’s a better place than docs. Let’s skip my off-topic comment and move along…

Last edited by Bloke (2020-12-03 22:13:15)

Destry · 2020-12-03 22:33:37

Bloke wrote #327244:

I’m never sure whether this is marketing (.com) or documentation, or if it somehow falls between the cracks.

One key to thinking about what content should go where is when that content is needed in a user journey. (Egads, I’m falling into buzzspeak again.)

User docs are usually a content wanted after a decision has been made to commit to the software, though sometimes certain parts of docs can help influence the decision (e.g. how easy is this to install).

Questions around ‘what can this software do’ would typically come earlier in the journey, before commitment.

So I’d agree it leans more to marketing and belongs on big sign posts where users first have contact, typically .com homepage, or a call to action there pointing out a link where to learn more about that kind of enquiry.

That doesn’t mean some thinking outside the box isn’t warranted, but it could be a design/presentation issue as much as location issue.

gaekwad · 2020-12-04 17:12:12

Auto-installer how to. I can take dibs on that.

gaekwad · 2020-12-06 07:58:41

Clear walkthrough of backing stuff up, database and files. Could consider (e.g.):

browser options (Adminer / phpMyAdmin etc)
desktop apps (Sequel Pro etc)
CLI (though command line jocks probably already know how to do this)

Destry · 2020-12-06 10:44:01

I’ve made the topics list in the head post three lists now.

User docs have always been meant to have a core functionality scope. (I think we even focused on that when moving the docs to versioning, and I think it’s even written in the existing guidelines, ~~but I can’t recall offhand for certain~~ yes). That scope is useful when you consider how much work goes into documentation and how few people ever want to (or can) help with it.

Regardless, that hasn’t always been what gets put in user docs. The old wiki was all over the place, and even now there is plugin development docs and branding materials.

So the scope of documentation probably needs revisited and discussed again before we get too far. Also, how docs can be leveraged with another platform like Textpattern Tips should be kept in mind.

Frankly, when you remember what all we’ve been through with docs in 16 years, and the decisions made to get to this point, such as more refined scope, more editorial control for sake of quality… and that people just like posting in the forum regardless how good or bad docs might be, I wonder if we don’t just realize there was nothing wrong with docs as they are, and nothing was really needed other than continuing to do what was already slated.
¯\_(ツ)_/¯

(Though I think there is merit in leveraging the User Docs and Forum better as a complete help system.)

In the meantime, keep all ideas coming.

Last edited by Destry (2020-12-06 13:17:34)

dos · 2020-12-06 12:02:39

I agree that the docs should be about core functionality. Other CMS have something like a cookbook (Kirby) or recipes for tutorials/how tos. That could be the place for “how can I do xy”.

The difference is, that the docs describe features and recipes are a collection of “how can you achieve a certain goal with this features”.

I’d love to see a recipe for getting started with a traditional blog layout for example.

Edit: Ghost is doing a good job with organizing the docs: Core Concepts, Install/Setup, theme documentation and Tutorials&Guides…

Last edited by dos (2020-12-06 12:05:10)

Bloke · 2020-12-06 12:40:55

I quite like the Ghost topic subdivision there. Good call, dos, thank you.

That does remind me that we really need to look into bolstering the import mechanism (officially) and maybe write a com_import plugin to assist with migration from other places. It’s better to have a plugin than roll it into core. More reactive to changes.

Having a “How do I move my content to Textpattern from ABC-Other-CMS” might be a nice topic area one day. I suspect as long as the other CMS can export content as XML we should be golden. Anything other than that (CSV, for example) might be pushing it right now.

Anyway, that’s an aside: please carry on!

Destry · 2020-12-06 16:40:04

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)

Bloke · 2020-12-06 18:19:20

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.

Textpattern CMS

Textpattern CMS support forum

#1 2020-12-03 14:32:41