Conventions

The conventions detailed in this chapter should be followed when modifying the project documentation to maintain readability and consistency.

Typographic

Italic

Used to introduce new terms. Italics used solely for emphasis should be avoided. When introducing new terms, only the first use should be set in italics, and its introduction should be followed with a definition or description of the term.

Example:

The |ATS| object storage is based on a *cyclone buffer* architecture.
Cyclone buffers are most simply described as a fixed size, but
continually looping block of storage updated by a single writer
process, wherein the writer continually reclaims the oldest allocations
for the most recent object updates.

Bold

Bold typesetting is to be reserved for section, table, and glossary headings and should be avoided in paragraph copy.

Monospace

Used to indicate filesystem paths, variable names, language keywords and functions, and command output. Note that in the case of variables and functions, whenever possible references to their documentation should be used in place of simple monospace markup.

Example:

Documentation source files for |TS| are located in the ``doc/``
directory of the project source tree.

Bracketed Monospace

Used to indicate, within command or source code examples, variables for which the reader should substitute a value.

Example:

To examine a performance statistic of a running |TS| instance, you may
run the comand ``traffic_ctl metric get <name>``, replacing ``<name>`` with
the statistic you wish to examine.

Ellipsis

Used to indicate the omission of irrelevant or unimportant information. May also be used to separate matter to be treated in detail elsewhere.

Layout Styles

Block Content

Notes

Use of .. note:: blocks should be sparing. In most rendered forms, the note block will appear quite prominently and draw the readers’ eyes away from the surrounding copy. It is therefore advisable that the note itself provide enough context and detail to be read on its own, without a full reading of the surrounding copy.

Important Notes

The use of .. important:: callout blocks should be limited only to those situations in which critical information needs to be prominently displayed. Suitable use would include noting that resizing a cache voiume will result in Traffic Server resetting the cache contents to empty when the service is started. This is information that may not be obvious, or safe to assume, for the reader but which can significantly (and negatively) impact the use and performance of Traffic Server in their environment. Important note blocks should not be used for behavior or actions which generally do not have potential negative side effects.

Sidebars

The use of .. sidebar:: blocks in Traffic Server documentation should be avoided, and note blocks favored in their place.

Code Samples

Content should be set within .. code:: blocks whenever a full line or multiple lines of source code are being included in the documentation, or when example shell or network commands are being demonstrated. Blank lines may be used to separate lines of code within the block for readability, and all normal indentation practices should be followed. No additional markup should be used within the content block.

Definition Lists

Definition lists may be used in multiple ways, not just for the term listings in the glossary section. They may be used to provide individual detailed treatment for a list of function or command arguments or where any series of terms need to be explained outside of the formal glossary.

Ordered Lists

Explicityly numbered ordered lists should be avoided. reStructuredText provides two methods of marking up ordered, numbered lists, and the automatic numbering form should be used in all cases where surrounding paragraphs do not need to reference individual list entries.

Tables

Tabular content may be used in any situation where a selection of items, terms, options, formats, etc. are being compared or where a grouping of the same are being presented alongside a small number of attributes which do not require detailed expositions.

The Traffic Server project documentation supplies a custom styling override which causes cell contents to wrap within wide tables whenever possible in cases where it is necessary to prevent the content from overflowing into the margin. If, however, the cell content cannot be wrapped because there are no breaking spaces present (for example, a long variable name containing only letters, periods, underscores, dashes, and so no, but no whitespace), the table may still require overflowing into the page margin. Whenever possible, please try to avoid the use of tables when presenting information that will lead to this, as it greatly hampers readibility on smaller screens, especially tablets and mobile devices. Alternatives such as a definition list may be better suited to the content.

Tables may be marked up using any of the reStructuredText styles, though it is generally easiest to maintain those using the simple table markup style.

Structural

Common Definitions

The Traffic Server project documentation maintains a common definitions, abbreviations, and shortcut listing in the file doc/common.defs. This file should be included by all reStructuredText source files after the standard project copyright notice.

The file should always be included using a relative path from the current file’s location. Any commonly or repeatedly used abbreviations, especialy those of product, company, or person names, should be added to the definitions file as useful to avoid repetitive typing and ensure accurate spellings or legal usage.

Tables of Content

Any chapters of non-trivial scope should begin with a table of contents on the chapter index. The :depth: option for the table of contents may be set to a value appropriate to the amount of content in the chapter sections. A depth of 2 will generally provide a balance between usefully describing the contents of the chapter without overwhelming a reader scanning for topics relevant to their needs or interests.

Sections and Headings

Each chapter section should be located in a separate reStructuredText file. Each file should contain the standard project copyright notice first, followed by a unique reference marker for the section.

While reStructuredText itself does not define a fixed ordering of section markers, Traffic Server documentation source files should use the same set of single line section markings, proceeding through the section levels without skipping. For consistency, the following section line markers should be used in order:

Top Level
*********

Second Level
============

Third Level
-----------

Fourth Level
~~~~~~~~~~~~

Any section file which reaches or has need to exceed the fourth level style of section line markings is an excellent candidate for breaking into several smaller, and ideally more focused, reStructuredText source files and referenced by an index with its own table of contents.

Footnotes and Endnotes

Both footnotes and endnotes should be avoided. The Traffic Server documentation is intended primarily for online viewing and the positioning of footnotes in the rendered output is not always intuitive. In cases where a footnote might have been appropriate in print-oriented material for referencing an external resource, that reference is more ideally integrated as a standard reStructuredText reference.

For more descriptive content that might have been included as a footnote, it is less disruptive and more useful to choose between reformullating the text to simply include the additional wording, or consider the use of an inline note block.

Grammatical