Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Offline
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
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
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
Re: Docs site refresh effort
I think I like and agree with all that.
One thing here..
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
I like the mix, and I agree not one pattern will work for every title (so rules shouldn’t be too rigid, in fact). But with respect to the three starting with ‘Websites:’, I’m easily seeing a series heading on those instead that pulls the repetitive part out, for example:
Website types
- Custom blog (site-blog.md)
- Mom and pop e-shop (site-eshop.md)
- Corporate headquarters (site-corporate.md)
- Nonprofit (site-nonprofit.md)
- . . .
But does that then leave titles too concise and relying on the header?
That probably also means re-thinking the Basics/More organization of index2, but that might have been inevitable anyway. ‘Basics’ might still be good as a first list in each section, but the ‘More’ items could be re-thought for breaking out into two or three specific groupings?
Let’s see what other fish bite and then aim for some constructive advice to update the collab doc with. The index architecture is a related but different discussion, perhaps.
Last edited by Destry (2020-12-10 18:10:00)
Offline
Re: Docs site refresh effort
I am now beginning work on the project-level editorial style guide. It’s only 5+ years overdue.
I will keep fine-tuning the collaboration doc as I go, so the previous conversation on titles is still valid.
Last edited by Destry (2020-12-11 10:08:18)
Offline
Re: Docs site refresh effort
I’ve started the ball rolling with a tags schedule: forum.textpattern.com/viewtopic.php?pid=327758
Comments and feedback welcome.
Offline
Re: Docs site refresh effort
Shall we start on the tags docs? A week or so late, but y’know… posted/modified/expires shouldn’t be too hard as they’ve not changed much over the years.
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: Docs site refresh effort
I’m aware that we’ll need to tweak things slightly, btw. Currently (as of Txp 4.8.4) break is a per-tag attribute, and is thus included in the common presentational atributes include file. As of 4.8.5 due imminently, break becomes global so it’ll have to move to the global atts include file.
That means any tags we link with common presentational attributes will need their break="" argument removing. Currently, no biggie, as the only tag that uses the new includes is the section_list tag.
I’m wondering given the imminent nature of 4.8.5 whether to add break to the global atts now to save us having to revisit the tags next week. It’s kinda naughty to document something that’s not in a release yet but, y’know, saved effort and all that. Thoughts?
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: Docs site refresh effort
Sorry I dropped this, real life stuff got in the way and threw me off course a bit.
Bloke wrote #328259:
Currently (as of Txp 4.8.4)
breakis a per-tag attribute, and is thus included in the common presentational atributes include file. As of 4.8.5 due imminently,breakbecomes global so it’ll have to move to the global atts include file.[…]
It’s kinda naughty to document something that’s not in a release yet but, y’know, saved effort and all that. Thoughts?
+1 for doing it. No harm in doing it now and noting that changes happened in 4.8.5, since there will inevitably be a long tail of people running pre-4.8.5 anyway.
Offline
Re: Docs site refresh effort
Oki doke, done. Just gotta decide what the best default value is for break. Traditionally it’s been ‘br’ but now it’s global I’m not so sure if that’s still the case, as it may be unset by default.
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: Docs site refresh effort
Bloke wrote #328261:
Just gotta decide what the best default value is for
break. Traditionally it’s been ‘br’ but now it’s global I’m not so sure if that’s still the case, as it may be unset by default.
We should first agree on what the global break should do. For example, in <txp:site_name break="br" />?
Offline