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 Writing guidelines
  12 ------------------
  13 Following these writing guidelines will keep ONAP documentation
  14 consistent and readable. Only a few areas are covered below, as
  15 we don't want to make it too complex. Try to keep things simple
  16 and clear, and you can't go far wrong.
  17
  18 Don’t get too hung up on using correct style. We’d rather have you
  19 submit good information that does not conform to this guide than no
  20 information at all. ONAP’s Documentation project team will be happy
  21 to help you with the prose.
  22
  23 General guidelines for all documents
  24 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  25 -  Use standard American English and spelling
  26 -  Use consistent terminology
  27 -  Write in the active voice, using present simple tense when possible
  28 -  Write objective, professional content
  29 -  Keep sentences and paragraphs short and clear
  30 -  Use a spell checker
  31
  32 Abbreviations and acronyms
  33 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  34 -  Write out the term the first time it appears in the document,
  35    immediately followed by the acronym or abbreviation in parenthesis.
  36    Then use the acronym in the rest of the document. In diagrams, if
  37    space allows, write out the full term.
  38
  39 -  Use “an” before an acronym that begins with a vowel sound when spoken
  40    aloud; use "a" before an acronym that begins with a consonant
  41    sound when spoken aloud.
  42
  43    +  Examples: an MSO component, a LAN, an L3-VPN
  44
  45
  46 ONAP terms
  47 ^^^^^^^^^^
  48 -  AA&I vs AAI: AAI should be used.
  49
  50 -  APP-C vs APPC: APPC should be used.
  51
  52 -  SDN-C vs SDNC: SDNC should be used.
  53
  54 -  Heat vs HEAT: Both are in use. The official website uses "Heat".
  55
  56 -  life cycle vs lifecycle or life-cycle: "life cycle" is preferred.
  57
  58 -  open source (adjective): capitalize only in titles; avoid
  59    "open-source". (Based on prevalence on the web.)
  60
  61 -  run-time vs. execution-time (adjective): prefer run-time.
  62    Example: "run-time logging of events"
  63
  64 -  run time (noun). Example: "logging of events at run time".
  65
  66 GUI elements
  67 ^^^^^^^^^^^^
  68 -  In general, write menu names as they appear in the UI.
  69    For example, if a menu or item name is all caps, then write
  70    it all caps in the document.
  71
  72 Headings (Titles)
  73 ^^^^^^^^^^^^^^^^^
  74 -  Use brief, but specific, informative titles. Titles should give
  75    context when possible.
  76
  77 -  Use sentence-style capitalization; do not end with a period or colon.
  78
  79 -  Use a gerund to begin section titles. Examples: Configuring,
  80    Managing, Starting.
  81
  82 -  Use descriptive titles for tables and figures titles. Do not
  83    number tables or figures. Do not (in general) add titles for screen shots.
  84
  85 Tasks
  86 ^^^^^
  87 -  Start task titles with an action word. Examples: Create, Add,
  88    Validate, Update.
  89
  90 -  Use [Optional] at the beginning of an optional step.
  91
  92 -  Provide information on the expected outcome of a step, especially
  93    when it is not obvious.
  94
  95 -  Break down end-to-end tasks into manageable chunks.
  96
  97
  98 ONAP Conventions for the Use of Sphinx Directives
  99 -------------------------------------------------
 100
 101 Needs Directive
 102 ^^^^^^^^^^^^^^^
 103
 104  * Needs IDs must match the regular expression "^[A-Z0-9]+-[A-Z0-9]+"
 105
 106  * The prefix (string before the dash) must be described in the following table
 107
 108 .. list-table:: Needs Prefix Use
 109    :align: center
 110    :widths: 8 40 40
 111    :header-rows: 1
 112
 113    * - Prefix
 114      - Description
 115      - Use
 116
 117    * - R
 118      - Represents a requirement that must be met by a VNF provider
 119      - Defined only in the vnfrqts project repositories, may be referenced in any project repository source