[wiki] TXP (written copy) Style Guide

It’s a Google doc, and Goog docs are probably the best thing goog has created besides the search engine. You can expect some more TXP goog-oriented docs from me. The style guide is public read only. This isn’t to enforce dick + potato = *dictator*-ship, it’s simply to keep the mal-intents out.

So how can you contribute to it? Add your thoughts to this thread.

Please keep this in mind…

This guide aims to remain as simple and readable as possible. Style guides that become tombs by trying to define everything under the sun are never used. We aren’t going down that path. The emphasis is on the writing, not the code. We assume here that people who know code will know how to add it to the documentation correctly (e.g., smart quotes vs. straight quotes), or will fix it where they see it wrong somewhere else. For that reason, let’s not get bogged down in creating a how to write like a developer in user documentation thing. Code in the docs is mainly used in the Tag Reference, which is mostly edited by code-savvy people anyway.

Re: [wiki] TXP (written copy) Style Guide

destry wrote

The name “TextBook” is being phased out. The wiki’s new name is Textpattern CMS User Documentation. While this is a little longer, it is much more clear in meaning and will serve indexing objectives better too. All references to “TextBook” should be changed accordingly, beginning with the wiki and other sites in the Textpattern family.

That makes me sad in a way. Don’t get me wrong, I do see you POV. It does leave me with a problem though: in my Sand Spaces admin theme, I include a link to the documentation wiki. TextBook is short and sweet (and takes up very little space), where as Textpattern CMS User Documentation is a mouth full and (in the context of the admin UI esp) takes up a huge amount of space.

Re: [wiki] TXP (written copy) Style Guide

Thanks, everyone. I’m glad nobody’s overly put off by a style guide. It will definitely help more than hurt.

In fact, as this thread is already showing, the style guide should really be adopted across all Textpattern communication, not just the wiki. At the very least it would include .com, .org, the dialogue in the UI of the admin-side (including popup help items), and one or two more other resources I know are in the pipeline. :)

That doesn’t mean a complete application of the style guide to every bit of content in some cases, so the style guide would evolve to make those exceptions. For example, it’s probably not reasonable to expect plugin developers to write their plugin help to a style guide, though in my opinion it would be great if they did. And, of course, what people say in a forum post would be exempt too, that sort of thing. What’s important is really the official stuff, and the UI.

phiw13 wrote:

That makes me sad in a way.

I hear you. But I think it was time to align better.

my Sand Spaces admin theme, I include a link to the documentation wiki. TextBook is short and sweet (and takes up very little space), where as Textpattern CMS User Documentation is a mouth full and (in the context of the admin UI esp) takes up a huge amount of space.

So glad you brought this up. I’ve noticed this in a couple of admin-side themes (Zanders’, for example), and it should be corrected in those. I also think it requires a special consideration in the style guide for Admin-side themes.

Els’ suggestion for “Txp Docs” is good, though why not just “Documentation”? If it’s in context of the admin-side, then the “Txp” part is assumed, and thus not really necessary. And “documentation” is better than just “docs”. (I’m looking for comments on this thought before writing it into the guide.)

The thing I mostly want to iron out, for this and other uses, is a definitive use of the abbreviation. As I brought up elsewhere, I think we need to look to the future and decide if “TXP 5” is really going to be the brand, as it were. I keep seeing it written like that, so I’m under the impression it’s the objective. But if that’s true, then we should universally adopt “TXP”. If you look at one of the new logos, the one where the hammer and chisel forms the “X”, it reflects a “TXP” appearance. So if this is the direction, then I would put in the style guide that we stop using “Txp”. Frankly, any time someone can avoid using an abbreviation, they should. But when it’s reasonable, it should be consistent. (Again, looking for comments on this.)

Oh, and thanks for picking up the typo! Good eye.

@joebaich: Good eye to you too, sir. That goes back to what I was just saying—that the style guide should probably evolve to include other content, such as admin-side dialogue, including in themes.

Oh, and that reminds me. I did a clean install of 4.4.1 recently and noticed the pre-installed links still use “TextBook”. That needs changed.

Re: [wiki] TXP (written copy) Style Guide

fwiw I’ve traditionally referred to TXP in shortened form for three reasons:

laziness

brevity / space (e.g. smd_calendar docs which would otherwise be too big to fit in the database)

search assistance

I always put both TXP and Textpattern in my site meta data and sprinkle both in copy text so the search engines can assimilate them both and cast a wider net when people search for “txp plugins” or “textpattern plugins” for example.

Also, as an FYI, I’ve just replied to progre55 on the issue of roles vs levels vs groups. Not sure if that sort of thing should also go in the style guide as we forge towards TXP 5. It needs defining somewhere; perhaps the main user documentation is better.