Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#31 2020-12-05 16:38:13

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

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

#32 2020-12-05 16:53:11

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

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

#34 2020-12-06 12:01:02

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

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

#35 2020-12-08 15:02:39

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

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

#36 2020-12-08 18:02:03

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

Re: Docs site refresh effort

Destry wrote #327292:

Good question, mistress.

Bloke wrote #327355:

Did I do good, boss?

I’m not sure where this thread tone is headed, but I’m looking around nervously for any Human Resources staff ready to swoop.

Offline

#37 2020-12-08 20:18:28

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

Re: Docs site refresh effort

Bloke wrote #327355:

Did I do good, boss? Did I? :)

No boss here (just tying up a few sheets in the wind). But you are on a roll, yes. 👍

this* is a great example

Offline

#38 2020-12-09 14:29:50

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

Re: Docs site refresh effort

The docs collaboration procedures have been, rather dichotomously, extended and refined.

It is now, I hope, ready to have its issue closed, but I need another pair of eyes to read it through for copy edits, link checks, and feasibility of collaboration procedures. Therefore, this may not be one person, but two, looking at different things.

Any takers with repo access, self-assign. Others can simply home-read and report back here. Thanks!

Oh, the mentioned issue for a ‘custom blog’ doc in the last wrap-up section has not actually been created yet, but it will be. ;)

Last edited by Destry (2020-12-09 15:07:36)

Offline

#39 2020-12-10 14:35:16

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

Re: Docs site refresh effort

Titles

Notably titles for digital documentation.

They have always been a challenge, even when some guidelines for creating them are available. I’ve added a section for that in the collaboration doc. Find it from the contents list. But I’m not happy with that section yet. Some community input on the wider lens would be useful first.

This recent conundrum is relevant, too, but my objective is not only to title that doc better; it is to revise the collaboration section about creating effective titles so it better helps authors going forward (including myself), provides a means for fixing existing titles, and avoids having or wanting to revise titles after they are approved for publication. (Many existing file names are another annoyance, to which I’m partly guilty, but that’s not the issue now, so don’t worry about broken links.)

You probably didn’t know (until the editorial style guide is ever produced), but we use the Oxford Style Manual (and the complementary OED) as baseline style guidance for Txp platform content. Unfortunately, we don’t get much help there on this issue. It offers a lot of gold on the formatting of existing titles in various use cases, but nothing in terms of syntactical structure when creating titles. I know there are technical documentation books that cover this kind of thing, but I don’t have any anymore. I do have an ancient edition of Rosenfeld’s Information Architecture, though I doubt that will have the dope we need either.

So here we are. We need a few concise and effective ideas for thinking up good doc title structure (and some examples) so people get it right the first time, mostly.

Off the top of my head, titles should:

  • Be concise and focused on doc topic, and if possible, scope.
  • Front-load subjects whenever possible (i.e. put subject terms at start of title; good for website usability).
  • Be free of punctuation, if possible (also good for usability but may require a compromise at times).

The first point suggests all kinds of easy wins, and that is more or less covered in the collaboration doc section… Don’t use: brand name (Textpattern), genre labels (‘how to’, ‘walkthrough’, ‘FAQ’, etc), more parts of speech than needed (articles, conjunctions, etc), and so forth. Comment on those if you like.

The latter two are more to the current dilemma. It’s not always easy to front-load, and especially without using punctuation, and for that reason I don’t suggest we require not using punctuation or always having to front-load subjects.

Before I say more, what thoughts might you have on this. Let’s collaborate! ;)

Any tech doc editing resources you might have laying around that gets to the meat of it, please quote the relevant bits for consideration.

Offline

#40 2020-12-10 16:40:16

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

Re: Docs site refresh effort

My primary goal for titles would be to align them with topics that users typically want. I know, grandiose and unattainable, but hear me out.

Assuming (broadly) that search engines use stemming, whether we use the gerund (creating) vs the imperative (create) in doc titles is immaterial. However, our own search within the docs might not be so smart as it’s limited by whatever we can do in Jekyll or JavaScript, and these might favour exact match/keyword matches.

Considering what people commonly want to know, and how they ask, guides our topic titles to more closely align. So I’m either for the:

Topic: gerund action(s)

or:

Gerund action a topic

format depending on context.

For context, the needs aren’t necessarily universal. When installing Txp for the first time, front-loading the title with the ‘topic’ clearly isn’t going to work:

  • Software: installing
  • Installation: upgrading
  • Installation: moving

Yuck.

In those instances, the question people ask is “how do I install Textpattern?” or “how do I upgrade Textpattern?” which maps nicely to “Installing the software” and “Upgrading the software” (since “Textpattern” is implied). “Moving an installation” is fine, as is “Multi-site installation”, “Configuring a web server” and “Troubleshooting common problems”. In fact, all the setup topics are pretty spot on, imo. Come the revolution, “Migrating a site from another CMS” fits nicely here too.

On the flipside, when it comes to using the software, starting with the gerund makes no sense, else everything starts with ‘Creating’ or ‘Building’ or ‘Editing’, which means you’re then hunting further along for the subject.

So in the Construction and Presentation area, the format of the title for the Themes doc makes more sense. The user is thinking “There’s a ‘Themes’ entry in the interface, I wonder how I create one or edit it?” And that maps nicely to “Themes: creating, editing and sharing”. It also gives more information: “Oooh, I can share themes too? Cool! That must mean I can download them from somewhere.” And, boom, more bang for the title.

Following this thematic device to its conclusion gives us things like this mix of title formats:

  • Content: managing articles, images, files and links
  • Websites: building a simple blog, with comments
  • Websites: building a photoblog
  • Websites: building a corporate site
  • Extending a site with plugins: installing and upgrading
  • Skinning the back-end: custom admin themes
  • Plugins: creating and developing

and so forth.

Tags too. Front-loading with ‘Tags:’ throughout won’t help, but as we have it now is probably okay with the mix of ‘Learning about’ and ‘Tags index’ and ‘Attributes cross-reference’. I’d tentatively suggest ‘Shortcodes: creating and editing custom tags’ might be a nice topic title. However, discussion around short-tags themselves – opt-in and purely to save typing or make things clearer in complex templates – should probably be its own subtopic page, as it would be linked out from the ‘building a site’ workflow as well as (probably) appearing in the ‘tags’ area on the index page.

In terms of content, inline pophelp covers all the mechanics of “what is this thing” (and if it doesn’t, any offending pophelps should be rewritten to cater to this need). But how these individual screen elements are threaded into a narrative of “this is how you do some specific task, end-to-end, using this on-screen doohicky” is where the docs come in.

So, from any pophelp itself, further assistance on how this particular on-screen widget fits into the whole ecosystem should be obtainable by following a link to the full documentation, imo.

Does that make sense? Anything I’ve misappropriated or not considered?

Last edited by Bloke (2020-12-10 16:45:21)


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