Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: [wiki] TXP (written copy) Style Guide
Textpattern CMS Documentation – documents about the Textpattern CMS
Textpattern CMS User Documentation – documents about Textpattern CMS Users
I like the first one better myself.
Offline
Re: [wiki] TXP (written copy) Style Guide
There are two kinds of documentation for just about everything manufactured:
- Docs that describe how the thing was built (manufacturing docs)
- Docs that describe how to use said thing (consumer docs)
Sometimes there’s a little overlap, and with software this is especially true, but by and large they are two different blue prints.
“Textpattern CMS Documentation” sounds like manufacturer docs to my ears, while the other makes it clear it’s for people like me. But the distinction in this case—for an open source CMS—is probably small or lost on most people. If you want to save 5 characters, I’m not going to complain.
But where was this a problem, again? Because maybe this is a context thing and we can simply use “User Documentation”. E.g., a logo already identifies the product as “Textpattern CMS”, so a tagline or whatever doesn’t have to repeat that.
Ed. Ah, I realize now you mean for links, perhaps? Well, if we had decided a one official abbreviation to use (i.e., Txp or TXP), then I would have said just use“Txp User Docs” or “TXP User Docs”, but since the majority rule was to leave abbreviations free-wheeling, then we’re forced to write it out on an official level. Otherwise, we lose having any consistent identity in links at all.
Last edited by Destry (2011-07-28 20:06:23)
Offline
Re: [wiki] TXP (written copy) Style Guide
I’m not too keen on shortening “Textpattern CMS” to “TXP” as it sets a precedent that abbreviation is fine to use. For Search engine optimisation TXP is pretty meaningless, unless someone is already familiar with Textpattern – it’s all about brand recognition these days.
Offline
Re: [wiki] TXP (written copy) Style Guide
I agree with the setting a precedent part as far as it goes for authoring. But, I’m less concerned about SEO for SEO’s sake; rather I more concerned for human understanding and the content being properly marked up.
I mean we could (and probably should) be doing things like this when a link label itself is not written out fully for whatever reason:
<abbr title="Textpattern CMS">TXP</abbr><a href="#" title="Textpattern CMS User Documentation">TXP User Docs</a>
But again, it demands a constant use of abbreviation, not just what anybody feels like using.
How about using this? Textpattern CMS User Docs I think it’s a lot less confusing to abbreviate “documentation” than to drop “user”.
Offline
Re: [wiki] TXP (written copy) Style Guide
Of course, we could say Textpattern User Docs and it’s shorter still without losing any brand identity. Remember, it’s about context. So if a link reads like this one, and then brings a person to a page where they see Textpattern CMS somewhere. It’s fine. It’s in context. People will make the mental cross-over easily enough. ‘Oh, this thing is a CMS…cool’.
Offline
Re: [wiki] TXP (written copy) Style Guide
Textpattern CMS User Docs works for me. I’ll go with that unless someone provides a valid argument against.
Offline
Re: [wiki] TXP (written copy) Style Guide
An intermission from the balcony: When Textbook was still titled “Textbook”, one did not find it on the first Google page for “textpattern documentation” or “textpattern manual”. This is bad UX. SEO ist important.
Offline
Re: [wiki] TXP (written copy) Style Guide
For the record, I didn’t say SEO wasn’t important (and natural referencing is a more important than black hat tricks). I said it was less important to me than human understanding, meaning people before machines. (Somebody has to care.)
Aside from the clever kitsch, “TextBook” was probably the worst thing the wiki could have been named, in retrospect, because as far as Google was concerned a “texbook” was some big academic hardcover book used in universities. There’s no way the docs for a lowly O-source project was going to compete in rankings on that.
Under the same thinking, “CMS” is a fairly diluted ranking word too, but I guess combined with the name it does provide more distinguishing weight.
The issue, here, though, if I understand correctly, was how to use link text in a clear way (not how the metadata was used). If I’m wrong, then Phil needs to explain better what he means. I think we all agree “Textpattern” is better than “TXP”, and “TXP CMS” looks stupid. But for comprehension about what the wiki is, I think “user” was an important word to not lose. It’s fairly understood that “docs” means “documentation” so that was a safe change, IMO.
Offline
Re: [wiki] TXP (written copy) Style Guide
My discussion was purely for the external links that appear in the default install of Textpattern (to replace the current “Textbook” link) – I think that “Textpattern CMS User Docs” is fine just for that – and obviously keep the actual website title and references elsewhere as the full title of “Textpattern CMS User Documentation”.
My aversion to using TXP as an abbreviation in those links is that it would encourage people to constantly refer to Textpattern as TXP when writing articles and suchlike – which has no SEO benefit for the project.
Hope I’ve explained myself a bit better now.
Last edited by philwareham (2011-07-29 09:03:36)
Offline
Re: [wiki] TXP (written copy) Style Guide
For the use case Phil raises (an external link in the default Textpattern site template), I prefer the full thing: Textpattern CMS User Documentation (space isn’t at such a premium price in that template, no matter how you turn it). ‘Docs’ has a cheap sound to it.
When I first raised the issue upthread, I was explicitly referring to a link in the TXP admin interface.
Where is that emoji for a solar powered submarine when you need it ?
Sand space – admin theme for Textpattern
phiw13 on Codeberg
Offline
Re: [wiki] TXP (written copy) Style Guide
Philiippe, I know you were talking about the admin side directly, but from a purely aesthetic point of view “Textpattern CMS User Documentation” is just so much longer than, for example, “Textpattern CMS Plugins” so any saving in characters that could balance that out a bit better would be nice. And I felt that ‘user’ is superfluous anyway.
People searching for instructions on how to use Textpattern are likely going to type “textpattern documentation” into their search engine.
Offline
Re: [wiki] TXP (written copy) Style Guide
philwareham wrote:
… from a purely aesthetic point of view “Textpattern CMS User Documentation” is just so much longer than, for example, “Textpattern CMS Plugins” so any saving in characters that could balance that out a bit better would be nice. And I felt that ‘user’ is superfluous anyway.
the ‘User’ could be dropped, no objection(s) about that.
Where is that emoji for a solar powered submarine when you need it ?
Sand space – admin theme for Textpattern
phiw13 on Codeberg
Offline
Re: [wiki] TXP (written copy) Style Guide
Which one of these do you want?
- Textpattern CMS Documentation
- Textpattern CMS User Docs
Whatever is decided is how it will remain in the style guide from here on.
Ed. Note if it’s the first, then anywhere “User Documentation” is currently used (like the forum, etc.) should be changed, again, to just “Documentation”, which would be consistent with the name on the wiki home page.
Last edited by Destry (2011-07-29 11:32:46)
Offline
Re: [wiki] TXP (written copy) Style Guide
Textpattern CMS Documentation
Offline
Re: [wiki] TXP (written copy) Style Guide
Offline