Textpattern CMS user documentation.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
_drafts Add some initial Jekyll files Aug 1, 2015
_includes Renamed manifest.json to site.webmanifest Oct 12, 2018
_layouts Start code migration Sep 4, 2018
_recycle/out-of-scope/tutorials Prep for forum domain migration Sep 13, 2018
administration Update languages-panel.md Oct 12, 2018
brand Start code migration Sep 4, 2018
development Prep for forum domain migration Sep 13, 2018
faqs Prep for forum domain migration Sep 13, 2018
feeds Not using posts on this site either Aug 15, 2017
img Slimming Sep 28, 2018
installation Update configuring-a-web-server-for-textpattern.md Oct 23, 2018
js Replace three dots with horizontal ellipsis Aug 6, 2018
search Start code migration Sep 4, 2018
tags Try again Nov 15, 2018
themes Prep for forum domain migration Sep 13, 2018
.editorconfig Markdown rule in editorconfig Jan 19, 2017
.gitignore Don't version control Gemfile.lock Dec 19, 2016
404.html Start code migration Sep 4, 2018
BingSiteAuth.xml Bing Webmaster Tools file Feb 23, 2017
CNAME Update CNAME Sep 4, 2018
Gemfile Add some initial Jekyll files Aug 1, 2015
LICENSE.txt Add license Oct 25, 2016
README.md Start code migration Sep 4, 2018
_config.yml Start code migration Sep 4, 2018
apple-touch-icon-120x120.png Latest Textpattern branding assets Sep 12, 2018
apple-touch-icon-152x152.png Latest Textpattern branding assets Sep 12, 2018
apple-touch-icon-167x167.png Add iPad Pro touch icon size, remove obsolete Sep 28, 2018
apple-touch-icon-180x180.png Run images through latest ImageOptim Dec 1, 2016
apple-touch-icon-precomposed.png Run images through latest ImageOptim Dec 1, 2016
apple-touch-icon.png Run images through latest ImageOptim Dec 1, 2016
browserconfig.xml Textpattern.com is HTTPS now Sep 6, 2017
favicon-16x16.png Amended favicons for better clarity in MacOS Mojave Safari 12 Dark Mode Sep 28, 2018
favicon-192x192.png Run images through latest ImageOptim Dec 1, 2016
favicon-32x32.png Amended favicons for better clarity in MacOS Mojave Safari 12 Dark Mode Sep 28, 2018
favicon-512x512.png Add manifest.json Mar 8, 2017
favicon.ico Amended favicons for better clarity in MacOS Mojave Safari 12 Dark Mode Sep 28, 2018
google308292a5db415192.html Google Search Console verification Dec 21, 2016
hi.png Add a couple of referenced images Aug 25, 2016
hi@2x.png Add a couple of referenced images Aug 25, 2016
index.md Link to server instructions from homepage Oct 23, 2018
mstile-150x150.png Favicons Oct 19, 2016
mstile-310x150.png Favicons Oct 19, 2016
mstile-310x310.png Run images through latest ImageOptim Dec 1, 2016
mstile-70x70.png Favicons Oct 19, 2016
robots.txt Start code migration Sep 4, 2018
site.webmanifest Renamed manifest.json to site.webmanifest Oct 12, 2018
yandex_b74359ed225c2888.html Yandex Webmaster Tools verification file Feb 27, 2017

README.md

Textpattern CMS user documentation

See the built website. This is the new user documentation, and it's a work in progress.

On this page are guidelines for doc authors:

Contributing documentation

Helping to edit current documentation and/or writing new documentation by Textpattern users is strongly encouraged!

If you are familiar with Git/GitHub workflows then you can fork this repository, make your edits/additions and then open pull request. A member of the core documentation team will then review you changes and merge into the repository once approved. The site is built using Jekyll every time a file change is detected, and the page is then live for everyone to see.

For simple, smaller edits, you can edit documents in-browser on GitHub as follows:

  1. Log into GitHub in your browser.
  2. Go to the docs repo (this repo!).
  3. Find the documentation page you want to add an example too, pages are within sub-directories of root and all labelled logically.
  4. Select the 'Edit this file' button (it's a little pen symbol).
  5. Write/edit content (in Markdown syntax).
  6. Press the 'Commit changes' button when finished – that will create a pull request. A member of the core documentation team will then review you changes and merge into the repository once approved.
  7. Jekyll rebuilds automatically when file changes are detected and the page is then live for everyone to see.

Filename (URL) conventions

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 Markdown formatting, not Textile. Jekyll uses the kramdown syntax of Markdown.
  4. Ensure filenames have .md extension.
file-download-description.md

Document page structure

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

  1. Start page with an h1 (# in Markdown) 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. If you have more than three h2 (## in Markdown) 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:
  • adding "On this page:" in normal text, followed by
  • an unordered list of links to the h2 headers only (e.g. [Header label](#xxx)), and
  • use #xxx as the anchors, where xxx is the heading text in lowercase with hyphens (i.e. for linking to ## Example heading the anchor would be (#example-heading)).
  1. Avoid using h4-h6 header levels, if possible, especially h5-h6. Deep structuring means the copy is too complex for new-user docs. Try and structure content with h2-h3 only (and h4 if really necessary).
  2. Use kramdown footnotes in a given section for any 'tips' or side details not needing said in the primary paragraph. Use a subsequent number for each new footnote on the page, even if they're not in the same section. (Footnote examples)

Concise copywriting tips

To improve the ability to scan pages as described above, write as concisely as you can. 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.)

Brand identity

  • Do not use "Txp" and "TXP". While these pet uses are convenient in the support forum, they lend confusion to brand awareness in official docs. The world is still confused between "Textpattern" vs. "TextPattern", for example. 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.

Administration-side references

Important rules for consistency, which also has implications for plugin authors.1

  • Use "administration side" correctly when used as an adjective versus a noun:
    • noun form (no hyphen is used): e.g. "The login to the administration side is located at …" (Write "administration" out fully to distinguish the place from a person ("admin").
    • adjective form (hyphen is used): e.g. "The administration-side panels are organized by Content, Presentation, and Admin (and Extensions for admin-side plugins). As the example shows, you may use "admin-side" when used as an ajective, due to it's popularity and convenience, but writing it out fully as "administration-side" is always preferred.
  • When referring to admin-side panel names, panel section headers, form control labels, and button labels, spell the name exactly as it appears in the panel and make it strong emphasis (double-asterisks each side in kramdown), e.g. "The articles table on the Articles panel shows article IDs, titles, dates posted, the sections they're in, and their current status."
  • When referring to a preference label, specifically, quote the text and make it italic (double underscores each side). For example: "You can control widowed words in article titles by selecting 'Yes' on the 'Prevent widowed words in article titles?' preference."
  • When referring to a form control options (e.g. select-menu options, radio button options, etc.) or any other non-header UI dialogue, quote the text and leave it in normal format. E.g. "When you're ready to publish your draft, change status to 'Live' and select the Save button."
  • When referring to system feedback dialogue (green, yellow, red), format the text exactly as it appears in the UI messages.2
  • When referring to file names, make them italic and include the extension. e.g. .htaccess and index.php (do not make them appear as code, unless they are part of a code snippet).

Note 1: Plugin authors must follow same editorial rules in their plugin help files.

Note 2: There should be three CSS class selectors to use in the Jekyll site that makes this easy, one for each feedback color type, even providing the background colour.

Typo and grammar gotchas to watch out for

  • User docs are written using British English spelling and punctuation conventions.
  • 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").
  • Do not use 'tab' - use 'panel' - when talking about the admin-side panels.3 The only exception is you're specifically referring to a UI text element where the word is encoded (e.g. in Basic preferences, the preference "Default admin tab").4

Note 3: 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. 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. The use of 'tab' in the admin-side UI, such as in preferences, help dialogue, and so forth, is probably only clear to veteran Textpattern users. 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.

Note 4: These uses of 'tab' in the admin-side UI preferences, for example, should be treated as bugs that need fixed, and issues written for them.

Markup

Tables

Use tables sparingly (they can be problematic to read on small screen devices), and only where the content is definitely tabular data (if the content can semantically be called a definition list, then use that context instead). Use HTML tags for tables within Markdown files, like this:

<div class="tabular-data" itemscope itemtype="https://schema.org/Table">
    <table>
        <thead>
            <tr>
                <th scope="col">Header</th>
                <th scope="col">Header</th>
                <th scope="col">Header</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <th scope="row">data</th>
                <td>data</td>
                <td>data</td>
            </tr>
            <tr>
                <th scope="row">etc</th>
                <td>etc</td>
                <td>etc</td>
            </tr>
        </tbody>
    </table>
</div>