doc style guide notes

[Jon Sime <js...@omniti.com>]

Per the Documentation Roadmap, I've been putting together notes for a
new style guide. The primary goals being improvements to consistency,
quality, and readability for the docs. I've included, after receiving
some initial feedback, the updated version of those notes below for
criticism, discussion, and refinement. I've also been working through
the Admin guide and a few referenced sections elsewhere to apply these
proposed standards as a showcase (diffs to follow in a few days).


Section Naming and Section Reference Markup
    - All documents should begin with a named local reference definition.
    - To avoid conflicts and ambiguity, all document and section name
references should begin with 'admin', 'sdk', 'reference', or 'arch'
followed by a dash and then the section
    - Section name references should be all lowercase and use only
single dashes to separate words
    - Reference name should match the document or section title
    - Abbreviation is acceptable in reference names, but not rendered names
        .. _admin-arch-and-hacking:

        Architecture and Hacking
        ************************
    - Examples:
        Balancer plugin reference page becomes "_reference-balancer-plugin:"
        Session protocol admin guide becomes "_admin-session-protocol:"
    - Grammatical forms that emphasize the function or feature first
are preferred:
        - Improves consistency and readability
        - Eases scanning table of contents lists
        - Preserves logical function grouping in automatically generated indices
        - E.g. "Logging API Guide" is preferred over "Guide to the Logging API"

Markup used to refer to a plugin by name
    - Standardize on reference markup (:ref: prefix preferred over suffix)
        :ref:`<section>-<plugin-name>`
    - Source document will begin with
        .. _<section>-<plugin-name>:
    - Title of source document being referenced should be as below,
with no definite article
        <Plugin-Name> Plugin
        ********************

Markup used for plugin parameters
    - Plugin configuration example should be set within a blockquote
(indented in RST with no preceding markup)
    - Plugin parameters should be listed one per line with newline escape:
        map http://foo.com http://foo.com \
            @plugin=balancer.so \
            @pparam=--policy=hash,url \
            @pparam=one.bar.com \
            @pparam=two.bar.com
    - Makes individual parameters easier to distinguish from each other
    - Additional markup cannot be used within the markup to highlight
parameter names or values

Markup used for program command line options
    - Each program's reference documentation should contain a section
'Options' detailing all available comment line arguments
    - The Options section should begin with the program name
        .. program:: binary_name
    - Followed by each option with a brief description of the
argument's function and possible values
        .. option:: -F, --foo

            Lorem ipsum dolor amet.
    - Variations of the argument name (short/long versions, etc.)
should be shown together as a comma separated list, in order of
shortest to longest variations
    - If the option accepts an arbitrary value of a particular type,
that should be expressed as the all uppercase type name (e.g. REGEX,
VAR, VALUE, etc.)
    - If the option accepts as a value a choice from an enumeration,
that should be expressed as a list of the acceptable values, separated
by ' | ' and enclosed in square brackets

Markup used for installation paths (/etc/trafficserver)
    - All filesystem paths should be marked up as inline literals
        ``/usr/local/lib``
    - Base installation paths should always begin with /
    - Relative paths should include the appropriate configuration prefix name
        ``$PREFIX/bin``

Markup used for configuration variables
    - All configuration variables mentioned in documentation should be
enclosed in the following markup, automating links to the
documentation for that variable:
        :ts:cv:`proxy.config.cache.ram_cache.size`
    - Values for variables should be marked up as inline literals when
part of a paragraph body.
        The default value of ``-1`` means ...
    - For configuration variables with an enumerated list of possible
values, those values should be provided in a simple table, with the
default noted:
        ======= ==========================
        Value   Meaning
        ======= ==========================
        0       No compression (*default*)
        1       *fastlz* compression
        2       *libz* compression
        ======= ==========================
    - All variables should be documented in the reference docs in the
following manner, using the ts:cv syntax:
        .. ts:cv:: <context> <variable name> <type> <default value>

           <Description of variable's function and use.>
    - If a configuration example is being provided with specific
values to enable/disable/modify a feature, it should:
        - Be provided, for purposes of clarity, as a fully formed
configuration line, within a literal block.
        - Be preceded in the body text with a :ts:cv: reference to
that configuration variable's documentation, as a workaround to RST's
lack of support for nesting reference markup within blockquotes.
            To remove the limit on size of objects which may be
cached, adjust :ts:cv:`proxy.config.cache.max_doc_size` in
:file:`admin-records.conf`::

                CONFIG proxy.config.cache.max_doc_size INT 0

Markup used for footnotes
    - All footnotes should be autonumbered
        [#] Lorem ipsum dolor amet.
    - All footnotes should use labels, instead of depending on
ordering in the document
        Fidgeting with the discombobulator sprockets[#sprockets]_ is
rarely necessary.
        .. [#sprockets] Lorem ipsum dolor amet.
    - Symbolic footnotes should not be used

Markup for formatting blocks of code
    - The code-block blockstyle markup should be used, including the
language to be used for syntax highlighting when possible:
        .. code-block:: c

           TSVIO TSVConnWrite (...)

Markup for function references
    - Source documentation for the C/C++ functions should contain a
local reference definition with the function signature:
        .. c:function:: TSReturnCode TSMutexLockTry(TSMutex mutexp)
    - All references to this function should be made via :c:func: markup:
        :c:ref:`TSMutexLockTry`

Markup used for URLs
    - All URLs within regular body text and footnotes should use the
standard embedded URI reference markup.
    - All URLs not being used as a literal example (e.g. a curl
command line) or as a configuration parameter (e.g. remap
configurations) should be named, e.g.:
        Refer to Example Corp's `Foo product page
<http://example.com/foo>`_ for more details.
    - URL references should always avoid the use of filler phrases
such as "Click here" and instead should always use a meaningful, short
name for the page which is being referenced.

Markup used for referring to arguments of a command line utility from
within descriptive paragraphs:
    - Use the :option: reference syntax to automatically link to
program documentation, anchored at the relevant argument's
explanation, e.g.:
        Use the command :option:`traffic_line -x` to reload the
running configuration of Traffic Server.
    - Use simple emphasis when describing the utility or purpose of an
argument, or a plugin option, by anything other than its actual name,
e.g. the second argument to a map rule is referred to as the
"Replacement URL" even though that phrase appears nowhere in the
configuration statements themselves (it is just the terminology used
to determine the second argument's utility from that of the first
argument's):
        When configuring the :ref:`balancer-plugin`, the *replacement
URL* in the ``map`` rule is not used.

General Guidelines:
    - Always specify the (default) units when referencing data
sizes/lengths for the first time within a documentation section, or
when documenting configuration options with accept sizes as values,
even if the unit may be commonly understood or expressed as part of
the variable/option name, e.g.:
        The response length (in bytes) from origin server ...
    - Numbered lists should use auto-numbering whenever possible, with
the exception of cases in which list entries must refer to each other.
        #. First entry.
        #. Second.
        #. And so on.
    - Individual words or phrases should only be placed in emphasis
(single asterisks) according to the common practices of
Chicago-Turabian/NY Times/AP style guides:
        - Keywords, or "words described as words"/"letters as letters"
should be emphasized for their first use, but not thereafter. E.g.
            The term *cluster* refers to a collection of servers.
Clusters may consist of anywhere from a single server to many
thousands or more.
        - Untranslated non-English phrases not in common use in English speech.
        - Publication and article titles, for every use.
    - The use of "scare quotes" should be avoided.
    - Individual word emphasis on negations should be used sparingly,
and only when clarity requires such in text that contrasts the
positive and negative options/outcomes; e.g.:
        - "Suchandsuch should *not* be frobulated." should omit the
emphasis as there is no contrasting phrase for which clarity demands
the emphasis.
        - Emphasis can be used in a construction such as: "Increasing
your cache partition size will *not* delete the contents of your
cache. However, decreasing the partition size *will* empty the cache
contents for that partition."
    - Definition lists and glossaries should provide a named reference
declaration for each entry if their defined items are referred to
elsewhere, to permit direct linking from other areas of documentation.
    - For readability and ease of reference, tables which display
mappings between two sets of related values (e.g. Squid logging fields
to ATS logging fields) should:
        - Avoid the use of inline literal markup around the pairs of values.
        - Use reference markup for the ATS values, linking to the
corresponding value documentation (when it exists).
            ============== ==============
            Squid          Traffic Server
            ============== ==============
            time           `cqts`_
            elapsed        `ttms`_
            ============== ==============

Re: doc style guide notes

[James Peach <jp...@apache.org>]

On Oct 7, 2014, at 2:58 PM, Jon Sime <js...@omniti.com> wrote:

> Per the Documentation Roadmap, I've been putting together notes for a
> new style guide. The primary goals being improvements to consistency,
> quality, and readability for the docs. I've included, after receiving
> some initial feedback, the updated version of those notes below for
> criticism, discussion, and refinement. I've also been working through
> the Admin guide and a few referenced sections elsewhere to apply these
> proposed standards as a showcase (diffs to follow in a few days).

This looks great Jon.

> Section Naming and Section Reference Markup
>    - All documents should begin with a named local reference definition.
>    - To avoid conflicts and ambiguity, all document and section name
> references should begin with 'admin', 'sdk', 'reference', or 'arch'
> followed by a dash and then the section
>    - Section name references should be all lowercase and use only
> single dashes to separate words
>    - Reference name should match the document or section title
>    - Abbreviation is acceptable in reference names, but not rendered names
>        .. _admin-arch-and-hacking:
> 
>        Architecture and Hacking
>        ************************
>    - Examples:
>        Balancer plugin reference page becomes "_reference-balancer-plugin:"
>        Session protocol admin guide becomes "_admin-session-protocol:"
>    - Grammatical forms that emphasize the function or feature first
> are preferred:
>        - Improves consistency and readability
>        - Eases scanning table of contents lists
>        - Preserves logical function grouping in automatically generated indices
>        - E.g. "Logging API Guide" is preferred over "Guide to the Logging API"
> 
> Markup used to refer to a plugin by name
>    - Standardize on reference markup (:ref: prefix preferred over suffix)
>        :ref:`<section>-<plugin-name>`
>    - Source document will begin with
>        .. _<section>-<plugin-name>:
>    - Title of source document being referenced should be as below,
> with no definite article
>        <Plugin-Name> Plugin
>        ********************
> 
> Markup used for plugin parameters
>    - Plugin configuration example should be set within a blockquote
> (indented in RST with no preceding markup)
>    - Plugin parameters should be listed one per line with newline escape:
>        map http://foo.com http://foo.com \
>            @plugin=balancer.so \
>            @pparam=--policy=hash,url \
>            @pparam=one.bar.com \
>            @pparam=two.bar.com
>    - Makes individual parameters easier to distinguish from each other
>    - Additional markup cannot be used within the markup to highlight
> parameter names or values
> 
> Markup used for program command line options
>    - Each program's reference documentation should contain a section
> 'Options' detailing all available comment line arguments
>    - The Options section should begin with the program name
>        .. program:: binary_name
>    - Followed by each option with a brief description of the
> argument's function and possible values
>        .. option:: -F, --foo
> 
>            Lorem ipsum dolor amet.
>    - Variations of the argument name (short/long versions, etc.)
> should be shown together as a comma separated list, in order of
> shortest to longest variations
>    - If the option accepts an arbitrary value of a particular type,
> that should be expressed as the all uppercase type name (e.g. REGEX,
> VAR, VALUE, etc.)
>    - If the option accepts as a value a choice from an enumeration,
> that should be expressed as a list of the acceptable values, separated
> by ' | ' and enclosed in square brackets
> 
> Markup used for installation paths (/etc/trafficserver)
>    - All filesystem paths should be marked up as inline literals
>        ``/usr/local/lib``
>    - Base installation paths should always begin with /
>    - Relative paths should include the appropriate configuration prefix name
>        ``$PREFIX/bin``
> 
> Markup used for configuration variables
>    - All configuration variables mentioned in documentation should be
> enclosed in the following markup, automating links to the
> documentation for that variable:
>        :ts:cv:`proxy.config.cache.ram_cache.size`
>    - Values for variables should be marked up as inline literals when
> part of a paragraph body.
>        The default value of ``-1`` means ...
>    - For configuration variables with an enumerated list of possible
> values, those values should be provided in a simple table, with the
> default noted:
>        ======= ==========================
>        Value   Meaning
>        ======= ==========================
>        0       No compression (*default*)
>        1       *fastlz* compression
>        2       *libz* compression
>        ======= ==========================
>    - All variables should be documented in the reference docs in the
> following manner, using the ts:cv syntax:
>        .. ts:cv:: <context> <variable name> <type> <default value>
> 
>           <Description of variable's function and use.>
>    - If a configuration example is being provided with specific
> values to enable/disable/modify a feature, it should:
>        - Be provided, for purposes of clarity, as a fully formed
> configuration line, within a literal block.
>        - Be preceded in the body text with a :ts:cv: reference to
> that configuration variable's documentation, as a workaround to RST's
> lack of support for nesting reference markup within blockquotes.
>            To remove the limit on size of objects which may be
> cached, adjust :ts:cv:`proxy.config.cache.max_doc_size` in
> :file:`admin-records.conf`::
> 
>                CONFIG proxy.config.cache.max_doc_size INT 0
> 
> Markup used for footnotes
>    - All footnotes should be autonumbered
>        [#] Lorem ipsum dolor amet.
>    - All footnotes should use labels, instead of depending on
> ordering in the document
>        Fidgeting with the discombobulator sprockets[#sprockets]_ is
> rarely necessary.
>        .. [#sprockets] Lorem ipsum dolor amet.
>    - Symbolic footnotes should not be used
> 
> Markup for formatting blocks of code
>    - The code-block blockstyle markup should be used, including the
> language to be used for syntax highlighting when possible:
>        .. code-block:: c
> 
>           TSVIO TSVConnWrite (...)
> 
> Markup for function references
>    - Source documentation for the C/C++ functions should contain a
> local reference definition with the function signature:
>        .. c:function:: TSReturnCode TSMutexLockTry(TSMutex mutexp)
>    - All references to this function should be made via :c:func: markup:
>        :c:ref:`TSMutexLockTry`
> 
> Markup used for URLs
>    - All URLs within regular body text and footnotes should use the
> standard embedded URI reference markup.
>    - All URLs not being used as a literal example (e.g. a curl
> command line) or as a configuration parameter (e.g. remap
> configurations) should be named, e.g.:
>        Refer to Example Corp's `Foo product page
> <http://example.com/foo>`_ for more details.
>    - URL references should always avoid the use of filler phrases
> such as "Click here" and instead should always use a meaningful, short
> name for the page which is being referenced.
> 
> Markup used for referring to arguments of a command line utility from
> within descriptive paragraphs:
>    - Use the :option: reference syntax to automatically link to
> program documentation, anchored at the relevant argument's
> explanation, e.g.:
>        Use the command :option:`traffic_line -x` to reload the
> running configuration of Traffic Server.
>    - Use simple emphasis when describing the utility or purpose of an
> argument, or a plugin option, by anything other than its actual name,
> e.g. the second argument to a map rule is referred to as the
> "Replacement URL" even though that phrase appears nowhere in the
> configuration statements themselves (it is just the terminology used
> to determine the second argument's utility from that of the first
> argument's):
>        When configuring the :ref:`balancer-plugin`, the *replacement
> URL* in the ``map`` rule is not used.
> 
> General Guidelines:
>    - Always specify the (default) units when referencing data
> sizes/lengths for the first time within a documentation section, or
> when documenting configuration options with accept sizes as values,
> even if the unit may be commonly understood or expressed as part of
> the variable/option name, e.g.:
>        The response length (in bytes) from origin server ...
>    - Numbered lists should use auto-numbering whenever possible, with
> the exception of cases in which list entries must refer to each other.
>        #. First entry.
>        #. Second.
>        #. And so on.
>    - Individual words or phrases should only be placed in emphasis
> (single asterisks) according to the common practices of
> Chicago-Turabian/NY Times/AP style guides:
>        - Keywords, or "words described as words"/"letters as letters"
> should be emphasized for their first use, but not thereafter. E.g.
>            The term *cluster* refers to a collection of servers.
> Clusters may consist of anywhere from a single server to many
> thousands or more.
>        - Untranslated non-English phrases not in common use in English speech.
>        - Publication and article titles, for every use.
>    - The use of "scare quotes" should be avoided.
>    - Individual word emphasis on negations should be used sparingly,
> and only when clarity requires such in text that contrasts the
> positive and negative options/outcomes; e.g.:
>        - "Suchandsuch should *not* be frobulated." should omit the
> emphasis as there is no contrasting phrase for which clarity demands
> the emphasis.
>        - Emphasis can be used in a construction such as: "Increasing
> your cache partition size will *not* delete the contents of your
> cache. However, decreasing the partition size *will* empty the cache
> contents for that partition."
>    - Definition lists and glossaries should provide a named reference
> declaration for each entry if their defined items are referred to
> elsewhere, to permit direct linking from other areas of documentation.
>    - For readability and ease of reference, tables which display
> mappings between two sets of related values (e.g. Squid logging fields
> to ATS logging fields) should:
>        - Avoid the use of inline literal markup around the pairs of values.
>        - Use reference markup for the ATS values, linking to the
> corresponding value documentation (when it exists).
>            ============== ==============
>            Squid          Traffic Server
>            ============== ==============
>            time           `cqts`_
>            elapsed        `ttms`_
>            ============== ==============