This is a lot. I don't think it looks bad, just feels like too much. I trust that we can present these in a way that makes it feel easy to understand and doesn't make someone want to just TL;DR.
On Wed, Oct 31, 2018 at 10:20 AM Fieck, Brennan <[email protected]> wrote: > 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? >
