See the Main Index.
This is the new user documentation, and it’s a work in progress.

On this page are guidelines for doc authors:

• Filename (URL) conventions
• Document page structure
• Concise copywriting tips

To ensure SEO friendly URL patterns, and for consistency, all directory names/file names should be structured using the following rules:

1. All text in lowercase.
2. Use hyphens, not underscores, to separate words within the URL.
3. Use Textile formatting (not Markdown).
4. Ensure filenames have .textile extension.

Example:

file-download-description.textile

Make doc pages scannable with a consistent structure across them, as much as possible. These guidelines can help:

1. Start page with an “h1” header that serves as the document’s title.
2. Where it’s reasonable to do so, follow the title with a brief introductory paragraph that sums up the page or it’s purpose (intro paragraph example).
3. Avoid using h4-h6 header levels, if possible. Deep structuring means the copy is probably too complex. Try and structure content with h2-h3 only.
4. If you have more than three “h2” sections on the page (or three that are kind of long), follow the h1 title (or intro paragraph, see previous example) with an in-page ToC (ToC example without intro paragraph). Do this by:
   1. adding “On this page:” in normal text, followed by
   2. an unordered list of links to the “h2” headers only (e.g., "Header label":#sec1), and
   3. use “#sec1”, “#sec2”, “#sec3”, etc as the anchors to make it easy every time (i.e., h2(#sec1). Header label).
5. Use footnotes in a given h2 section for any “Tips” or side details not needing said in the primary paragraph. Use a subsequent number for each new footnote, even if they’re not in the same section. (Footnote examples)

To improve the ability to scan pages as described above, write as concisely as you can, and use the style guide [link needed]. Here are a few quick wins for cleaner copy:

1. Write in the third-person. You’re speaking to an individual on behalf of Textpattern, so you don’t use “me”, “I”, “my”, etc. (But you will use “you”, “your”, etc.) When you don’t talk about something from your personal point of view, you say a lot less. It’s magic.
2. Avoid passive ‘to be’ and ‘to have’ verb structures (e.g., could be/have, should be/have, might be/have). Passive writing is not only miserable to read, it bloats copy with unnecessary words. Find a more direct/active way of wording the phrase. For example, instead of “The widget should be at the top of the sidebar.” say “Put the widget at top of the sidebar.”
3. Avoid useless adverbs like “very”, “really”, “only” and many others. For example, “If you really want to do that.” is better as “If you want to do that.” A person either wants to or doesn’t, adding “really” does’t change anything.
4. Question every use of “that” and “just” in your copy. It’s easy to abuse both words. Every time you use “that” or “just” in a sentence, read the sentence and see if it still makes sense without the word. Most of the time it will. If it does, it’s probably correct to leave the words out.
5. Avoid over use of adverbs, idioms, and other partial clauses at the beginning of sentences: “Meanwhile, …”, “On the other hand, …”, “However, …”, “In other words, …”, “Nevertheless, …” and so forth. This doesn’t mean never use them, but if you’re using them regularly, or more than once in a paragraph, then it’s too much. Rewrite the sentences more concisely without the clause breaks.
6. Remove words from your sentences until you can’t remove anymore for the meaning to remain clear.
7. Break long, multi-clause sentences into shorter sentences. (Careful here, though, sometimes a single longer sentence can read more smoothly if it’s free of needless word bloat. Multiple shorter sentences doesn’t mean result in choppy stilted reading. Use your best judgement.)

• User docs are written using British English spelling and punctuation conventions. But don’t kill yourself over it.
• Use “login” and “logout” when it’s a noun (e.g., “the login location”).
• Use “log in” and “log out” when it’s a verb (e.g., “after you log in” or “after logging in”).
• Avoid using “Txp” and “TXP”. While these pet uses are convenient in the support forum, they lend confusion to brand awareness in official docs. (E.g., the world is still confused about “Textpattern” vs. “TextPattern”). Always spell Textpattern out fully. This will also help you see if you’re using the name too repetitively, which can be a sentence bloat problem.
• The presentational theme of the admin-side was originally conceived as a set of manilla file folders, with each region label depicted as a folder “tab”. This presentational concept has left an impact on the mental models of long-time users, who will frequently refer to panels as “tabs” even though they may use an admin theme that does not depict the file folder concept. However, new docs should not perpetuate that false concept and terminology, particularly as the file folder concept is not depicted in the admin-side navigation of the official admin-side theme — Hive. You’ll even see the word “tab” used in the admin-side UI, such as in preferences, help dialogue, and so forth, which is probably only clear to veteran Textpattern users. For purposes of user documentation, “panel” and “tab” mean exactly the same thing, but docs will only use “tab” when a specific reference is being made to the admin-side UI where the word is still encoded in a label (e.g. the preference “Default admin tab”). When/if the admin-side UI is cleaned of all use of the word “tab”, then docs can be fully cleaned of the use as well, but we can get most of the way there by only using “tab” when it’s in direct reference of an UI element label.