You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficcontrol.apache.org by "Fieck, Brennan" <Br...@comcast.com> on 2018/11/07 14:05:45 UTC
Re: [EXTERNAL] Re: Documentation guidelines
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 <ne...@apache.org>
Sent: Tuesday, November 6, 2018 11:54 AM
To: dev@trafficcontrol.apache.org
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 <Br...@comcast.com>
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?
>
Re: [EXTERNAL] Re: Documentation guidelines
Posted by "Fieck, Brennan" <Br...@comcast.com>.
I have a PR in for this now: https://github.com/apache/trafficcontrol/pull/3133
I was unable to find a linter for reStructuredText that checked for anything other than compilation warnings/errors, unfortunately.
________________________________________
From: Fieck, Brennan <Br...@comcast.com>
Sent: Wednesday, November 7, 2018 10:03 AM
To: dev@trafficcontrol.apache.org
Subject: Re: [EXTERNAL] Re: Documentation guidelines
I could probably work out a simple linting system - it may even be configurable for Sphinx out-of-the-box.
________________________________________
From: Rawlin Peters <ra...@gmail.com>
Sent: Wednesday, November 7, 2018 8:37 AM
To: dev@trafficcontrol.apache.org
Subject: Re: [EXTERNAL] Re: Documentation guidelines
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 <Br...@comcast.com> 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 <ne...@apache.org>
> Sent: Tuesday, November 6, 2018 11:54 AM
> To: dev@trafficcontrol.apache.org
> 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 <Br...@comcast.com>
> 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?
> >
Re: [EXTERNAL] Re: Documentation guidelines
Posted by "Fieck, Brennan" <Br...@comcast.com>.
I could probably work out a simple linting system - it may even be configurable for Sphinx out-of-the-box.
________________________________________
From: Rawlin Peters <ra...@gmail.com>
Sent: Wednesday, November 7, 2018 8:37 AM
To: dev@trafficcontrol.apache.org
Subject: Re: [EXTERNAL] Re: Documentation guidelines
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 <Br...@comcast.com> 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 <ne...@apache.org>
> Sent: Tuesday, November 6, 2018 11:54 AM
> To: dev@trafficcontrol.apache.org
> 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 <Br...@comcast.com>
> 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?
> >
Re: [EXTERNAL] Re: Documentation guidelines
Posted by Rawlin Peters <ra...@gmail.com>.
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 <Br...@comcast.com> 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 <ne...@apache.org>
> Sent: Tuesday, November 6, 2018 11:54 AM
> To: dev@trafficcontrol.apache.org
> 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 <Br...@comcast.com>
> 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?
> >