You are not logged in.
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)
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 :-)
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
Have a look at this compared to above
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)
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
Don not use all-caps
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?
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.
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.
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.
fwiw I’ve traditionally referred to TXP in shortened form for three reasons:
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.