[wiki] TXP (written copy) Style Guide

Destry · 2011-06-30 16:47:34

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.

Last edited by Destry (2011-07-18 12:05:58)

Gocom · 2011-06-30 17:07:22

Cool stuff. Nice to have attention to detail.

Unfortunately I don’t really have anything to contribute to it :/ Maybe version numbering scheme could be added to the Style Guide, with also directions how to refer to versions older or newer than x.

Dimitri · 2011-06-30 19:06:37

Looks excellent. Would love to find time to help Textpattern ( read the docs for the wording :P ). I dont care about Wordpress or Joomla.

We need to beat expressionengine in marketing. Look all the supporting websites they have, it just beautiful and attractive.

I guess we just need to give a small makeover to the yellow colour scheme and fix that horrific looking textpattern.org

All we need to work on is
www.textpattern.com
www.textpattern.org
forum.textpattern.com

Have a look at this compared to above
http://www.expressionengine.com
devot-ee.com/ (Willing to help on that)
expressionengine.com/forums ( I like textpattern forum better, just needs a small improvement.)

We should make expressionengine our main competitor. We can win this by improving the marketing and it is always free, including most of the plugins.

If we win this, the developers of Textpattern will finally achieve what they need the most, source income personally and for the community.

(fixed the links. -Els)

Last edited by els (2011-06-30 22:49:34)

phiw13 · 2011-07-01 00:42:16

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.

Other than that, this is an excellent document!

Note: typo: Don not should probably be Do not

in

7.2 All-caps
Don not use all-caps

els · 2011-07-01 00:50:21

phiw13 wrote:

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.

Would Txp Docs be acceptable?

phiw13 · 2011-07-01 01:00:29

Els wrote:

Would Txp Docs be acceptable?

Same number of characters. Short and Sweet :-)

joebaich · 2011-07-01 01:46:24

Els wrote:

Would Txp Docs be acceptable?

Not if Destry has his way :-)

It is common to abbreviate “Textpattern” as Txp or TXP (TxP is never acceptable as it implies a camel-case spelling). While this might be fine …SNIP… it should not be used in user documentation.

Destry · 2011-07-01 07:30:05

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.

wet · 2011-07-01 08:12:17

Please collect all necessary code changes in this issue on the tracker.

Bloke · 2011-07-01 08:22:29

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.

Destry · 2011-07-01 10:22:24

So what I gather then is “TXP” is the desired abbreviation when an abbreviation is appropriate to use. Correct?

Destry · 2011-07-01 10:55:35

Gocom wrote:

Maybe version numbering scheme could be added to the Style Guide

I was just looking at that. Nice contribution. For the sake of keeping the guide concise, I’ll mention it but point to the actual policy, as that is something more strongly determined by core development.

@Dimitri: I love your enthusiasm. The style guide is an important step in the right direction for outward appearances, but in this case it’s a guide for communication, not presentation, exactly.

Textpattern CMS

Textpattern CMS support forum

#1 2011-06-30 16:47:34

[wiki] TXP (written copy) Style Guide

#2 2011-06-30 17:07:22

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

#3 2011-06-30 19:06:37

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

#4 2011-07-01 00:42:16

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

#5 2011-07-01 00:50:21

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

#6 2011-07-01 01:00:29

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

#7 2011-07-01 01:46:24

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

#8 2011-07-01 07:30:05

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

#9 2011-07-01 08:12:17

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

#10 2011-07-01 08:22:29

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

#11 2011-07-01 10:22:24

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

#12 2011-07-01 10:55:35

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

Board footer