docs/guides/onap-developer/how-to-use-docs/style-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0
   2 .. International License. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
   4
   5 Style guide
   6 ===========
   7
   8 This style guide is for ONAP documentation contributors, reviewers and
   9 committers.
  10
  11 Getting started
  12 ---------------
  13
  14 When is documentation required?
  15 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  16 All ONAP project contributions should have corresponding documentation.
  17 This includes all new features and changes to features that impact users.
  18
  19 How do I create ONAP documentation?
  20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  21 ONAP documentation is written in ReStructuredText_ (an easy-to-read,
  22 what-you-see-is-what-you-get, plain text markup syntax).  The process for
  23 creating ONAP documentation and what documents are required are
  24 described in later sections of this Developer Documentation Guide.
  25
  26 .. _ReStructuredText: http://docutils.sourceforge.net/rst.html
  27
  28 ReStructuredText markup conventions
  29 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  30 For detailed information ReStructuredText and how to best use the format, see:
  31
  32 - `ReStructured Text Primer <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>`_
  33 - `ReStructured Text Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
  34
  35 Writing guidelines
  36 ------------------
  37 Following these writing guidelines will keep ONAP documentation
  38 consistent and readable. Only a few areas are covered below, as
  39 we don't want to make it too complex. Try to keep things simple
  40 and clear, and you can't go far wrong.
  41
  42 Don’t get too hung up on using correct style. We’d rather have you
  43 submit good information that does not conform to this guide than no
  44 information at all. ONAP’s Documentation project team will be happy
  45 to help you with the prose.
  46
  47 General guidelines for all documents
  48 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  49 -  Use standard American English and spelling
  50 -  Use consistent terminology
  51 -  Write in the active voice, using present simple tense when possible
  52 -  Write objective, professional content
  53 -  Keep sentences and paragraphs short and clear
  54 -  Use a spell checker
  55
  56 Abbreviations and acronyms
  57 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  58 -  Write out the term the first time it appears in the document,
  59    immediately followed by the acronym or abbreviation in parenthesis.
  60    Then use the acronym in the rest of the document. In diagrams, if
  61    space allows, write out the full term.
  62
  63 -  Use “an” before an acronym that begins with a vowel sound when spoken
  64    aloud; use "a" before an acronym that begins with a consonant
  65    sound when spoken aloud.
  66
  67    +  Examples: an MSO component, a LAN, an L3-VPN
  68
  69
  70 ONAP terms
  71 ^^^^^^^^^^
  72 -  AA&I vs AAI: AAI should be used.
  73
  74 -  APP-C vs APPC: APPC should be used.
  75
  76 -  SDN-C vs SDNC: SDNC should be used.
  77
  78 -  Heat vs HEAT: Both are in use. The official website uses "Heat".
  79
  80 -  life cycle vs lifecycle or life-cycle: "life cycle" is preferred.
  81
  82 -  open source (adjective): capitalize only in titles; avoid
  83    "open-source". (Based on prevalence on the web.)
  84
  85 -  run-time vs. execution-time (adjective): prefer run-time.
  86    Example: "run-time logging of events"
  87
  88 -  run time (noun). Example: "logging of events at run time".
  89
  90 GUI elements
  91 ^^^^^^^^^^^^
  92 -  In general, write menu names as they appear in the UI.
  93    For example, if a menu or item name is all caps, then write
  94    it all caps in the document.
  95
  96 Headings (Titles)
  97 ^^^^^^^^^^^^^^^^^
  98 -  Use brief, but specific, informative titles. Titles should give
  99    context when possible.
 100
 101 -  Use sentence-style capitalization; do not end with a period or colon.
 102
 103 -  Use a gerund to begin section titles. Examples: Configuring,
 104    Managing, Starting.
 105
 106 -  Use descriptive titles for tables and figures titles. Do not
 107    number tables or figures. Do not (in general) add titles for screen shots.
 108
 109 Tasks
 110 ^^^^^
 111 -  Start task titles with an action word. Examples: Create, Add,
 112    Validate, Update.
 113
 114 -  Use [Optional] at the beginning of an optional step.
 115
 116 -  Provide information on the expected outcome of a step, especially
 117    when it is not obvious.
 118
 119 -  Break down end-to-end tasks into manageable chunks.
 120
 121
 122 ONAP Conventions for the Use of Sphinx Directives
 123 -------------------------------------------------
 124
 125 Needs Directive
 126 ^^^^^^^^^^^^^^^
 127
 128  * Needs IDs must match the regular expression "^[A-Z0-9]+-[A-Z0-9]+"
 129
 130  * The prefix (string before the dash) must be described in the following table
 131
 132 .. list-table:: Needs Prefix Use
 133    :align: center
 134    :widths: 8 40 40
 135    :header-rows: 1
 136
 137    * - Prefix
 138      - Description
 139      - Use
 140
 141    * - R
 142      - Represents a requirement that must be met by a VNF provider
 143      - Defined only in the vnfrqts project repositories, may be referenced in any project repository source
 144