Textpattern Forum

You are not logged in. Register | Login | Help

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

Destry
Moderator
From: Strasbourg, France
Registered: 2004-08-04
Posts: 2,365
Website

[wiki] TXP (written copy) Style Guide

Right here !

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)

Offline

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

Gocom
Developer
Registered: 2006-07-14
Posts: 4,476
Website

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

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.


Rah-plugins | What? I’m a little confused… again :-) <txp:is_god />

Offline

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

Dimitri
Member
From: Johannesburg
Registered: 2010-10-31
Posts: 129

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

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)


<txp:way_too_cool />

Offline

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

phiw13
Plugin Author
From: Japan
Registered: 2004-02-27
Posts: 613
Website

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.

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

Offline

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

Els
Admin
From: The Netherlands
Registered: 2004-06-06
Posts: 7,390
Website

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

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?


<txp:Els /> ;)
Tag Reference | Unexpected behaviour? Check the tag trace | Still no clue? Check the names of your custom fields

Offline

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

phiw13
Plugin Author
From: Japan
Registered: 2004-02-27
Posts: 613
Website

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

Els wrote:

Would Txp Docs be acceptable?

Same number of characters. Short and Sweet :-)

Offline

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

joebaich
Member
From: DC Metro Area and elsewhere
Registered: 2006-09-24
Posts: 477
Website

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

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.

Offline

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

Destry
Moderator
From: Strasbourg, France
Registered: 2004-08-04
Posts: 2,365
Website

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.

Offline

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

wet
Developer
From: Lenzing, Austria
Registered: 2005-06-06
Posts: 3,115
Website

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

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

Offline

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

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 5,979
Website

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

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

  1. laziness
  2. brevity / space (e.g. smd_calendar docs which would otherwise be too big to fit in the database)
  3. 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.


The smd plugin menagerie — for when you need one more gribble of power from Textpattern.

Txp Builders – finely-crafted code, design and Txp

Offline

Board footer

Powered by FluxBB