Skip to content

Coding guidelines

Jump to bottom Edit New page
Jarno Elovirta edited this page Jul 25, 2022 · 32 revisions

Please follow these guidelines when contributing changes to the DITA Open Toolkit docs.

Coding conventions

  • Use soft-tabs (spaces) with a two-space indent.
    (They're the only way to guarantee code renders the same in any environment.)
  • Nested elements should be indented once (two spaces).
  • Keep lines fewer than 120 characters.
    (This prevents horizontal scrolling in GitHub edit & unified diff views.)
  • Use UTF-8 encoding.
  • Trim trailing white space on save.
  • End each file with a blank newline.

Enforcing consistent formatting

Most of these preferences are defined in the oXygen project file and an .editorconfig file, so if you use oXygen to edit the docs or a tool that supports the EditorConfig convention, your editor should do the right thing.

We enforce these conventions with automated checks on pull requests, and provide formatting tools to apply these guidelines to the changes in each commit.

Terminology

We consider “DITA Open Toolkit” a proper name, so we try to avoid the definite article:

  • We refer to the product as the “DITA Open Toolkit” where the full name is justified.
  • The same logic applies to the abbreviation: the “DITA-OT”.
    • The abbreviation for DITA Open Toolkit is always hyphenated: DITA-OT. ⚠️ Don't write “DITA OT” (with a space).
  • To make text easier to read and avoid awkward repetitions of the full product name and/or abbreviation,
    we sometimes use generic references to “the toolkit” when the context is established.
  • We use “DITA Open Toolkit project” as a collective noun for the team of developers and maintainers.

The options for the DITA-OT transformations are called “parameters”, not properties or arguments.

In earlier toolkit releases, the full distribution package was called the “full-easy-install package”. Recent toolkit releases provide a single distribution package, with a .zip compressed version for both UNIX-based operating systems and Windows.

Download the distribution package for your operating system from the project website at www.dita-ot.org.

DITA-OT output formats are called “transformation types”. Avoid abbreviating to “transtype” or “transform type” unless explicitly referring to elements or attributes by name:

The <transtype> element defines an output format (transformation type).

The documentation hyphenates "plug-ins" except when referring to the <plugin> element or otherwise mirroring a non-hyphenated spelling, such as "Plugins" in the the DITA-OT website menu.

Tagging

DITA-OT parameters

  • Use <parmname> for the name of the parameter (and for DITA-OT extension points).
  • Use <option> for the permissible values for the parameter.
  • Use <option> for transformation types (output formats), as these are options passed to the transtype/--format parameter.

For example:

<cmdname>dita</cmdname> <parmname>--input</parmname>=<filepath>sequence.ditamap</filepath> \
                        <parmname>--format</parmname>=<option>html5</option>

Plug-ins

Use <codeph> or <filepath> for plug-in names. Rendering of both tags is currently identical in the distribution documentation output formats.

(Use <filepath> in cases where the plug-in folder is meant.)

Ant targets

Use <codeph> for Ant target names (as in processing modules topics).

(Pre)processing modules/steps

Use <codeph>.

DITA-OT error messages

Use <msgnum>.

Use only ASCII characters in error message copy because consoles displaying log messages may not support full Unicode.

Multi-platform tabs

To enable multi-platform tabs in site output, add the multi-platform class to the @outputclass attribute value. The following cases are supported:

  • <choicetable> where <chrow> elements have the @platform attribute.
    The contents of the <choption> element is used as the tab text and <chdesc> as tab contents.
  • <steps> where <step> elements have the @platform attribute.
    Tabs will wrap the whole step sequence.
  • <codeblock> with the syntax-bash class.
    Directory separators in nested <filename> elements, multi-line command delimiters, and prompt characters are dynamically rewritten to match the platform.

Avoid unnecessary markup

  • Don't litter the source files with generated IDs
    • If your editor automatically generates ID values for elements, remove them before committing.
    • If you need to link to an element, choose an ID value that reflects the contents. This helps to keep code readable and makes links more understandable.
  • Avoid block elements within list items unless the item contains more than one idea

Style guidelines

Use US English and The IBM Style Guide: Conventions for Writers and Editors.

For additional recommendations on syntax and markup conventions, see
The DITA Style Guide: Best Practices for Authors.

Information architecture

Indexing

This project uses the recommendations in "Chapter 10: Indexes" from The IBM Style Guide. The recommendations and any deviations are summarized here.

What to index

When creating or editing content, consider indexing:

  1. Any titles (topic, table, section, etc.)
  2. Any parameter, argument, option, or property
  3. Any extension point
  4. Any troubleshooting information, including error messages
  5. Any plug-in
  6. Any of these DITA elements:
    1. <parmname>
    2. <xmlelement>
    3. <xmlatt>
    4. <filepath>
    5. <codeph>
  7. Any third-party tool (Saxon, Apache FOP, etc.)
  8. Any deprecated feature
  9. Any note, tip, caution, warning, etc.

Where to place <indexterm>

In short topics, place index terms in the <prolog> element. In longer topics, use inline entries to direct the reader to the terms' usage. For more details, Placement of <indexterm> affects findability.

  1. Is there a <section> in the topic?
    1. If yes, then put the <indexterm> below the <title>.
    2. If not, then place the <indexterm> in <prolog>.
  2. Is there a table or any list element?
    1. If yes, the put the <indexterm> inline
      (unless the table or list is short — fewer than five rows/items).
    2. If not, then place the <indexterm> in <prolog>.
  3. Is the content in a warehouse topic of any sort?
    1. If yes, then put the <indexterm> inline in the warehouse topic.
    2. If not, then place the <indexterm> in the <prolog> of the destination topic. Do not put <indexterm> in the <prolog> of a warehouse topic. It will never be part of the finished output since warehouse topics have their processing-role set to resource-only.
  4. Is the content part of conref-push?
    1. If yes, then put the <indexterm> inline with the source content of the conref-push. Some conref-push for “empty” elements will now have <indexterm> as the sole push content.
    2. If not, then place the <indexterm> in <prolog>.

Writing <indexterm> content

  1. Use inline markup. For example, if something is <parmname> in the content, it should also be <parmname> inside <indexterm> (e.g., <indexterm><parmname>dita.temp.dir</parmname></indexterm>).
  2. Use lowercase unless it's a proper noun or trademark.
  3. Top-level entries should primarily be nouns and are always plural, unless the topic itself is singular (i.e., installation not installing; parameters not parameter).
  4. Second-level entries may take the form of gerunds or end with a preposition. Be as concise and descriptive as possible.
  5. Avoid third-level as much as possible.
  6. Do not create fourth-level entries.
  7. Use @start and @end to create index ranges.
  8. Create nested entries for any item in the index with six or more locators.

Placement of <indexterm> affects findability

The default recommendation for most DITA topics is to place <indexterm> in the <prolog>. This generally good advice can lead to a findability issue. If the <indexterm> is in the <prolog>, the locator page number will be for a page number where the <title> for that topic is found. For short topics this is usually not a problem, although it can be. For long topics that span two or more pages this is a problem. It is a problem because people will use the page number to turn or click to that page. Then they begin scanning the page looking for the term from the index. For long topics where the <indexterm> is in the prolog the term may be two or more pages away. Users should not need to understand how the index was created and generated to know that they might need to read the entire topic to find what they’re looking for. Compounding the issue is the use of <section> elements whose <title> element is styled such that one stops reading thinking it must be a new topic or that the section belongs to the <title> above. This is made even worse by topics with numerous sections. By not finding the term or concept on the page from the index the trust in the index is reduced. If this happens more than a couple of times the index will be deemed worthless and not used.

Do not index container topics.

View the latest DITA Open Toolkit docs at www.dita-ot.org/dev.

DITA-OT Docs Wiki

Clone this wiki locally