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`_ > ============== ==============
