Not a developer? Go to MovableType.com

MovableType.org
Documentation
Home / Documentation /

Documentation Style Guide

This page describes the information and presentation that all documentation on this site should follow.

This page currently covers the documentation of tags, modifiers, and config directives but the Content Outline and Formatting Requirements & Tips here can be extended to any of the documentation.

This guide is a work-in-progress that should be updated when necessary.

To become a contributor sign in with your account on this site and leave a comment below. You will be contacted with more information.

Style Guide Index

Conversion & Update Process

Until all the docs are complete, here is the process for completing documentation.

  1. convert current formatting to markdown.
  2. integrate legacy docs.
  3. integrate comments and mark as “feedback integrated”.
  4. review the perl code to compare for accuracy.
  5. add “tested” examples.
  6. tag accurately.
  7. spellcheck.
  8. preview and proof and edit until doc is solid!

Template Tag Docs

Template Tag Content Outline

  1. A short concise description of the tag’s default behavior should be the first line.
  2. A simple example
  3. Describe any additional common uses of the tag, using examples to support description.
  4. Attributes list (if applicable)
    • Note required attributes in sentence.
    • If more than three attributes, create index of tag attributes. Mark the most common attributes bold. Use three dashes to separate the index from the attribute details.
    • Describe each attribute.
    • Note acceptable values. Note default value with “(default)”. Note suggested values if the attribute is unusual.
    • Add a useful example for each attribute. Describe what the example does just before the example.
  5. Examples
    • One simple and one complex example at a minimum (unless linking to another tag page for more examples).
  6. Related
    • note related tags, documents, urls, etc.
  7. list all tags relevant to the doc, the more the better. (see below)
  8. Use callouts to inform of warnings, bugs, notes, tips, deprecation of tags, etc.

Template Tag Examples

Template Tag Documentation Skeleton

One sentence description of tag's purpose.

Simple Example

    <mt:FooBlock>
        <!-- tags here -->
    </mt:FooBlock>

Additional paragrahs of more detail with examples.

    <mt:FooBlock attribute="value">
        <$mt:FooFunction$>
        <!-- more tags here -->
    </mt:FooBlock>

## Attributes

(If many attrbutes, list an index of the attributes)

* [`attribute1`](#attribute1)
* [`attribute2`](#attribute2)

---

### attribute1

Description of attribute

### attribute2

Alias of [`attribute1`](#attribute1)

## Examples

### Title of Example

Description of example

    (code here)

## Related

* [`mt:Foo`](/documentation/appendices/tags/foo.html)
* [Calendar template tags](/documentation/appendices/tags/template-tag-types.html#calendars)
* [Template Tag Recipes](http://wiki.movabletype.org/path/to/page)

Config Directive Docs

Config Directive Content Outline

  1. A short concise description of the config directive’s purpose should be the first line.
  2. Default
    • Note default behavior with example showing default.
    • If default is disabled, under the “Default” just type “Disabled.”
  3. Values
    • Note if value is integer, boolean, filepath, url, etc.
    • Note recommended values, if necessary.
    • Note acceptable value range.
  4. Examples
    • One simple and one complex example at a minimum (unless linking to another tag page for more examples).
    • Describe each example in a sentence before the example. (Describing the same thing in two different ways aids in understanding.)
  5. Related
    • note related tags, documents, urls, etc.
  6. list all tags relevant to the doc, the more the better. (see below)
  7. Use callouts to inform of warnings, bugs, notes, tips, deprecation of tags, etc.

Config Directive Examples

Config Directive Documentation Skeleton

One sentence description of config directive's purpose.

## Default

Description of default:

    ConfigDirective DefaultValue

## Values

Description of possible values: `value1` or `value2`

## Examples

Description of example:

    ConfigDirective OtherValue

## Related

* [thing1](/link/to/thing1)
* [thing2](/link/to/thing2)

Modifier Docs

Modifier Content Outline

  1. A short concise description of the modifier’s purpose should be the first line.
  2. Describe any common uses of the modifier, using examples to support description.
  3. Values
    • Note if value is integer, boolean, filepath, url, etc.
    • Note recommended values, if necessary.
  4. Examples
    • Provide examples of common uses of the modifier. One simple and one complex example at a minimum (unless examples under the description are enough, or if linking to another page for more examples).
    • Describe each example in a sentence before the example. (Describing the same thing in two different ways aids in understanding.)
  5. Related
    • note related tags, documents, urls, etc.
  6. List all tags relevant to the doc, the more the better. (see below)
  7. Use callouts to inform of warnings, bugs, notes, tips, deprecation of tags, etc.

Modifier Examples

Modifier Documentation Skeleton

One sentence description of modifier's purpose.

## Values

Description or list of acceptable values.

### value1

Description of value1.

Example of value1:

    <mt:TemplateTag modifier="value1">

### value2

Description of value2.

Example of value2:

    <mt:TemplateTag modifier="value2">

## Examples

Description of example1:

    <mt:TemplateTag modifier="value3">

Result of example1:

    Foo Bar

## Related

* [thing1](/link/to/thing1)
* [thing2](/link/to/thing2)

Formatting Requirements & Tips

Language

  • Describe in simple concise language.

  • Use imperative rather than indicative phrases:

    Instead of:

    Use your blogs Manage Categories page to create your categories.

    Use:

    Create new categories on the Manage > Categories screen.

Examples

  • A simple example should be just after the description, such that usage can be seen w/o any necessary scrolling.
  • Examples should exist for each tag attribute and any important value of modifiers or config directives.
  • One simple and one complex example at a minimum.
  • Describe each example in a sentence before the example. (Describing the same thing in two different ways aids in understanding.)

Headings

  • Use ## for generic headings: Attributes, Examples, Related, etc
  • Use ### for all individual attributes
  • The header should only contain the name of the attribute, no other metadata such as: “(required)”, or “(optional)”, etc

  • Use a heading for each section such that all sections will have page anchors. Headings will be given an id using the HeadingAnchors plugin. Links to headings using this format:

    [`attribute1`](#attribute1)

Linking

  • Always provide link when referencing anything. eg. lastn for mt:Entries:

    [`mt:Entries lastn`](/documentation/appendices/tags/entries.html#lastn)

  • All links should be from the site root. eg. /documentation/author/tagging-entries-and-pages.html

  • Do not include a full url unless linking to another sub-domain or site. eg. http://google.com

  • Use these url shortcuts (variable name will be converted to lowercase, so this is case-insensitive):

    /tag/template-tag-name#optional-page-anchor
/config/config-directive-name#optional-page-anchor
/modifier/modifier-name#optional-page-anchor
/guide/name-of-guide#optional-page-anchor (not yet supported)

Template Tags

All tags should be marked up with as much context as possible; link to the page for the tag at a minimum.

  • use “mt:” prefix (lowercase “mt” and a colon).
  • use “$” for all function tags.

  • place open and closing block tags each on their own line.

    Code example:

    <mt:Entries>
    <$mt:EntryTitle$>
    <mt:EntryCategories>
        <$mt:CategoryLabel$>
    </mt:EntryCategories>
</mt:Entries>

    In-text example:

    2-digit minute, zero-padded. Same as [`<$mt:ArchiveDate format="%M"$>`](/documentation/appendices/tags/archivedate.html). Example: `04`

  • If white-space is important when viewing rendered html, then block tags can be placed on their own line:

    <mt:EntryTags glue=", "><$mt:TagLabel$></mt:EntryTags>

  • When referring to tags in text without an example:

    • don’t use angle-brackets or dollar signs
    • wrap in back-ticks to denote code: mt:Entries

    • link all tags other than the current tag in context. On the mt:EntryTitle page:

      The [`mt:EntryTitle`](/documentation/appendices/tags/entrytitle.html) tag is commonly used with the `mt:Entries` tag.

Lists

  • Lists should be in alphabetical order unless alphabetical order doesn’t makes sense.

Call Outs

  • Each call out should have that word followed by a color in bold and prefixed with a blockquote character.

    > **Tip:** Use short syntax for link urls: `/tag/TagNameHere`
> **Note:** Tags can be separated by commas or spaces. See [user settings](/guide/user-settings)
> **Warning:** this tag outputs data which when known may introduce security vulnerabilities.
> **Deprecated:** Use [`<$mt:ArchiveLink$>`](/tag/archivelink)
> **Bug:** there is a bug in this tag. See [case 101205](http://bugs.movabletype.org/default.asp?101205)

    Note: When used in markdown there must be an empty line between each call out, otherwise markdown assumes that all the lines are par of the same blockquote.

    Rendered:

    Tip:

    Tip: Use short syntax for link urls: /tag/TagNameHere

    Note:

    Note: Tags can be separated by commas or spaces. See user settings

    Warning:

    Warning: this tag outputs data which when known may introduce security vulnerabilities.

    Deprecated:

    Deprecated: Use <$mt:ArchiveLink$>

    Bug:

    Bug: there is a bug in this tag. See case 101205

    Styling of these call outs is handled with jQuery in the “Site Javascript” index template.

  • Place code in call outs using angle bracket and then a space (>) for the blockquote, then 4 more spaces for a code block:

    > **Tip:** Find the ID by looking for the `id` query string in an application URL:
>
>     http://yourdomain/cgi-bin/mt/mt.cgi?__mode=view&_type=template&id=384&blog_id=1
>     
> In this case, the template ID would be 384.

    Rendered:

    Tip: Find the ID by looking for the id query string in an application URL:

    http://yourdomain/cgi-bin/mt/mt.cgi?__mode=view&_type=template&id=384&blog_id=1

    In this case, the template ID would be 384.

  • Place lists in call outs:

    > **Tip:** Foo bar.
>
> 1. asdf
> 2. asdf

    Rendered

    Tip: Foo bar.

    1. asdf
    2. asdf

Tags

Use as many tags as possible without being redundant. Tags are used to categorize and aggregate documentation, so tagging will cause this tag to show up in various indexes of tags.

  • Use the singular version of tags rather than the plural, “entry” instead of “entries” and “category” instead of “categories”.
  • Always use lowercase unless referring to a proper name or using a phrase

For mt:Entries template tag page:

  • block = type
  • entry = tag type
  • loop = tag group
  • multiblog = tag group
  • score = tag group

Generic Tag Type

All pages should have only one of the following tags denoting type of document:

  • function
  • block
  • config
  • modifier
  • guide
  • appendix

Block Tag micro-types:

  • loop - type of block tag
  • conditional - type of block tag

Topic Based

Use all the following as necessary, these will be used for grouping on topic-specific indexes.

Don’t use the plural version entries or the tag name itself.

  • archive
  • asset
  • author
  • blog
  • calendar
  • category
  • comment
  • trackback
  • count
  • creative commons
  • date and time
  • entry - all Entry-related tags should have the tag .
  • feed
  • folder
  • id
  • logic
  • page
  • search
  • tag
  • app
  • system

Feature Based

Useful tags for grouping:

  • multiblog - for mt:Entries and mt:Pages and other related block tags
  • score - for a score-able objects: Entry, Page, Comment, Ping (TrackBack), Asset, Author.

If an existing document should be updated, make the necessary updates to the document for the version (noting differences between versions) and add the tag “Updated for MT5” using the respective version number.

  • New in MT4.2 - when feature is new in for this version.
  • Updated for MT4.3 - updated to contain info for this version.
  • Bug in MT4.261 - document topic is known to have a bug in this version. (Document should link to bug case.)

For each new version of MT, create a new folder named with the version number. Simplify the folder basename to MT + version number. Drop the “.0” for any major release.

For example for “Movable Type 5.0”:

/documentation/mt5/

For example for “Movable Type 4.32”:

/documentation/mt432/

An index template (published to the root of the version folder) should be created with mt:Pages loops for the following tags (example use MT5.0):

  1. New in MT5
  2. Updated for MT5
  3. Bug in MT5

See version related tags for a description of how these tags should be used.

Downside to using tags for aggregation is that the pages listed will be in order of publish date (unless some other sort method is used) instead of some other more useful order.

Ideally we’d have a more defined documentation structure with a topic hierarchy similar to the application menus and then the version tag loops could look for all pages in a particular folder tagged with the tag such as all pages in “Installation” folder tagged “New in MT5”.

Until an objective documentation structure is defined, the above option using tags offers the most utility and automation.

Back