We should try to codify any rules as much as possible with some kind of pre-build documentation parser/checker. Whatever rules can't be codified (e.g. "Consider an option or field list instead of a table") should be put in the documentation guidelines.
- Rawlin On Wed, Nov 7, 2018 at 7:05 AM Fieck, Brennan <[email protected]> wrote: > > Of course, I agree. This is just an incomplete list of things I'd want to > include in no particular order, syntax, or point of view. > > > 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. > > I don't mean to just throw a bulleted list at people. > ________________________________________ > From: Dave Neuman <[email protected]> > Sent: Tuesday, November 6, 2018 11:54 AM > To: [email protected] > Subject: [EXTERNAL] Re: Documentation guidelines > > 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? > >
