Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

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

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

Topic Suggestions for User Documentation

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)

Offline

#2 2020-12-03 18:52:06

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

Re: Topic Suggestions for User Documentation

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?


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

#3 2020-12-03 21:37:22

zero
Member
From: Lancashire
Registered: 2004-04-19
Posts: 1,407
Website

Re: Topic Suggestions for User Documentation

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


Wondrous Healing Wondrous ways to a healthy old age
Safe Reiki Harmless natural healing.
Gud One Blog

Offline

#4 2020-12-03 22:05:30

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

Re: Topic Suggestions for User Documentation

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)


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

#5 2020-12-03 22:33:37

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

Re: Topic Suggestions for User Documentation

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.

Offline

#6 2020-12-04 17:12:12

gaekwad
Admin
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 3,344

Re: Topic Suggestions for User Documentation

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

Offline

#7 2020-12-06 07:58:41

gaekwad
Admin
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 3,344

Re: Topic Suggestions for User Documentation

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)

Offline

#8 2020-12-06 10:44:01

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

Re: Topic Suggestions for User Documentation

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)

Offline

#9 2020-12-06 12:02:39

dos
Member
From: de
Registered: 2014-05-17
Posts: 37
Website

Re: Topic Suggestions for User Documentation

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)

Offline

#10 2020-12-06 12:40:55

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

Re: Topic Suggestions for User Documentation

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!


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

Board footer

Powered by FluxBB