this is my first pass at a set of standards for documentation updates: use `.. code-block:: <syntax>` not `::` Bold text is NOT a section/subsection heading use `*****` over/under for page titles, then in decending order: `====`, `-----`, `"""""` and `'''''` use `#.` for enumerated list items, `*` for unordered lists consider if your list needs enumeration consider if your list isn't actually just a definition list instead of `**NOTE**` or similar, use an actual `.. note::` or a footnote instead of `(see also <link>)` use an actual `.. seealso::` (until >2 refs, then use footnote) Spell check proofread use titles that can be easily referenced later, e.g. "Health Protocol" is good, but "Configuring Multi-Site Origin" as the title of a page which not only explains MSO configuration but also the concept of an MSO is not good You don't need to block-quote under section titles/subheads etc. Consider an option or field list instead of a table tables shouldn't be more than 215 characters wide Use tabs for indentation, NOT Spaces `TODO` is NOT an acceptable response example - if your new code is untested, then it isn't ready to be merged When making docs for a new API route, ALWAYS DOCUMENT ANY AND ALL QUERY PARAMETERS AND ANY AND ALL REQUEST BODY PARAMETERS - WHETHER THEY'RE OPTIONAL OR NOT No lines should match the regular expression `^\|$` NEVER add documentation that references the Traffic Ops UI - we Portal now Provide both SVG and PNG for images created as SVGs - pdflatex can't use SVGs to create PDF output for the documentation without special packages use `.. table:: <caption>` for tables, not just block-quoted floating tabular environments use `.. figure:: <src>`, NOT just floating images - and ALWAYS caption figures Figures should almost always be centered (and explicitly sized), but tables are generally left-aligned rather than saying e.g. "as discussed above", consider referencing the section directly as e.g. "as disscussed in `Some Other Section`_" - this is sometimes unavoidable, but note that both tables and figures are label-able! The first instance of an acronym, initialism, or abbreviation within a section (the `====` ones) MUST include the fully-expanded word, followed by the shorthand in parenthesis e.g. "Fully Qualified Domain Name (FQDN)" "Cache Group" not "cachegroup", "cache group", or "Cachegroup" Similarly, "Delivery Service" not "deliveryservice", "delivery service" or "Delivery service" Be careful using the word "cache", to most people that means the actual cache - maybe what you meant was "cache server"? When creating docs for a new API route that has path parameters, use mustache templates<https://mustache.github.io/mustache.5.html> NOT the Mojolicious-specific `:param` syntax Whenever possible, avoid manually specifying line breaks. It's okay to have extremely long lines, the user agent will decide where line wrapping is appropriate. A manual line break should ONLY be used to separate objects as required by reStructuredText syntax, or when separating paragraphs.
Obviously this isn't a totally complete list, and the idea for the final format is that it would be included in the Development section of the documentation, in a more appropriate order and more verbose explanations, including examples. What I'm looking for is this: Do any of these rules look bad to anyone?
