ocket8888 commented on a change in pull request #3133: Added documentation guidelines URL: https://github.com/apache/trafficcontrol/pull/3133#discussion_r242291250
########## 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 +- HTTP +- HTTPS +- IP/IPv4/IPv6 +- TCP +- UDP +- URL +- URI + +Please do **not** abbreviate Traffic Control terms e.g. Cache Group, Delivery Service. See `Terms`_ for the proper way to use these terms. + +Floating Objects +"""""""""""""""" +"Floating objects" are images, tables, source code listings, and equations. These may not be placed relative to other content exactly as shown in the source :abbr:`RST (reStructuredText)` document, as it may be necessary to move them for e.g. page breaks in PDF documents so they are not split across pages. + +Figures +''''''' +Images should *always* be included inside of a ``.. figure`` directive. **Always** caption figures to make their purpose clear, as well as to make them directly link-able inside of the document and include them in figure listings. Figures should, in general be sized *explicitly* but not *absolutely* i.e. use ``70%`` not ``540px``. Figures should, in general, be centered on the page. When drawings, graphs, or diagrams are included they should ideally be provided in both SVG and PNG formats, and included using globbing as ``filename.*``. This will use the appropriate format for the output type. Review comment: Figures don't _need_ a size specification to compile, that's what I'm trying to say. In general you should specify a size even though it isn't syntactically required. The size should not be absolute. ---------------------------------------------------------------- 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
