ocket8888 commented on a change in pull request #3133: Added documentation guidelines URL: https://github.com/apache/trafficcontrol/pull/3133#discussion_r243324496
########## File path: docs/source/development/documentation_guidelines.rst ########## @@ -0,0 +1,172 @@ +.. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + +.. _docs-guide: + +************************ +Documentation Guidelines +************************ +The Apache Traffic Control documentation is written in :abbr:`RST (reStructuredText)` and uses the `Sphinx documentation build system <http://www.sphinx-doc.org/en/master/>`_ to convert these into the desired output document format. This collection of guidelines does **not** aim to be a primer in :abbr:`RST (reStructuredText)`, but merely a style guide regarding how the components of the document ought to be formatted and structured. It may also point out some features of the markup language of which a writer may not be aware. + +.. seealso:: `The docutils RST reference <http://docutils.sourceforge.net/rst.html>`_. + +Building +======== +To build the documentation, see :ref:`docs-build`. + +Writing +======= +When writing documentation, the most important things to remember are: + +- Spell Check. Most text editors have this built in (e.g. "F6" in Sublime Text) or have plugins that will do this for you. +- Proof-Read. Spell-checkers won't catch grammatical errors or poor wording, so it's very important to actually proof-read all documentation *before* submitting it in a Pull Request. +- Make Sure the Documentation Actually Builds. Please actually verify the documentation not only builds, but builds *correctly*. That means there probably shouldn't be any warnings, no malformed tables etc. and it also means that new documentation is actually accessible once built. It's not enough to create a new ``.rst`` file, that file must actually be linked to from some other, already included document. Some warnings may be considered acceptable, but do be prepared to defend them. +- Traffic Ops UI is Dead. Do not ever create documentation that references or includes images of the Traffic Ops UI. That is officially dead now, and if the documentation being created is best made with references to a user-friendly UI, such references, examples and/or images should all be to/of Traffic Portal. + +Formatting +---------- +Whenever possible, avoid specifying manual line breaks, except as required by :abbr:`RST (reStructuredText)` syntax. Extremely long lines will be wrapped by the user-agent, compiler, or output format as necessary. A single blank line may be used to separate paragraphs. This means that the 'flow break' character should never need to be used, i.e. no line in the documentation should ever match the regular expression ``^\|$``. + +Abbreviations +""""""""""""" +When using an abbreviation, acronym or initialism for the first time on a page, it **must** be named fully and followed by the abbreviation in parentheses e.g. "Fully Qualified Domain Name (FQDN)". Strictly speaking, the *best* way to create an abbreviation is to always fully name it in parentheses immediately following the abbreviation using the ``:abbr:`` :abbr:`RST (reStructuredText)` text role e.g. ``:abbr:`FQDN (Fully Qualified Domain Name)```, but it's not reasonable to expect that of everyone. Some abbreviations can be assumed to be understood by the documentation's target audience, and do not need full naming; they are: + +- DNS Review comment: It's not about collision, it's about obscurity. You might not have a conflicting definition of ORT, but that doesn't mean you know what it means. The target audience of Traffic Control is people who want to set up a CDN. That means they know what a CDN is (roughly), and they're familiar with how a simple webserver serves HTTP(S) requests - that covers that list. For example I was hired and trying to set up a CDN-in-a-Box I didn't know what "ORT" meant until I found the definition in the docs. I did know (roughly) what a CDN is, and I understood what basic web technologies like HTTP and DNS are. "ORT" doesn't exist outside of Traffic Control, so we could never expect anyone to come into the documentation knowing what that is. To be clear, I'm not saying that "ORT" can't be used in the docs, I'm just saying the first time you use it on a page you should make it clear what it is. I don't actually think the best way to do that is to expand the initialism into "Operations Readiness Test" because that really doesn't give the user much more information. IMO, that should be treated as a `:term:` that will link to the glossary for a definition. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
