summaryrefslogtreecommitdiffstats
path: root/docs/guide/onap-developer/how-to-use-docs/style-guide.rst
diff options
context:
space:
mode:
authorRich Bennett <rb2745@att.com>2017-08-24 12:11:36 -0400
committerRich Bennett <rb2745@att.com>2017-08-24 16:44:10 +0000
commit1da304689093f1144d2be5cfb1fac6f29a158caa (patch)
tree36d5ceebd14c9ca5a6e6c854f52090bc72741c67 /docs/guide/onap-developer/how-to-use-docs/style-guide.rst
parent30b6487daa4c3a47ffa8fd290f46c261920f4201 (diff)
Update How To Guide & Git submodules
vnfrqts/requirements master advanced beyond submodule reference in doc before verify job available updated git reference to current level Improvements in the how to guide describing submodule integration Updated sphinx configuration to support sequence diagrams Temporary exclusion filter reduced for seed documents with severe errors Issue-Id: VNFRQTS-76 Change-Id: I3928a3d1e55a0731125e07186d8041b1614c3c8d Signed-off-by: Rich Bennett <rb2745@att.com>
Diffstat (limited to 'docs/guide/onap-developer/how-to-use-docs/style-guide.rst')
-rw-r--r--docs/guide/onap-developer/how-to-use-docs/style-guide.rst26
1 files changed, 14 insertions, 12 deletions
diff --git a/docs/guide/onap-developer/how-to-use-docs/style-guide.rst b/docs/guide/onap-developer/how-to-use-docs/style-guide.rst
index 8f9369b17..5d477a99b 100644
--- a/docs/guide/onap-developer/how-to-use-docs/style-guide.rst
+++ b/docs/guide/onap-developer/how-to-use-docs/style-guide.rst
@@ -6,34 +6,34 @@ Style guide
This style guide is for ONAP documentation contributors, reviewers and committers.
Getting started
-===============
+---------------
When is documentation required?
--------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All ONAP project contributions should have corresponding documentation. This includes all new features and changes to features that impact users.
How do I create ONAP documentation?
------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ONAP documentation is written in ReStructuredText_ (an easy-to-read, what-you-see-is-what-you-get, plain text markup syntax).
The process for creating ONAP documentation and what documents are required are described here: <<add links to Documentation process/automated tools sections>>
.. _ReStructuredText: http://docutils.sourceforge.net/rst.html
ReStructuredText markup conventions
------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For detailed information ReStructuredText and how to best use the format, see:
- `ReStructured Text Primer <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>`
- `ReStructured Text Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`
Writing guidelines
-==================
+------------------
Following these writing guidelines will keep ONAP documentation consistent and readable. Only a few areas are covered below, as we don't want to make it too complex. Try to keep things simple and clear, and you can't go far wrong.
Don’t get too hung up on using correct style. We’d rather have you submit good information that doesn’t conform to this guide than no information at all. ONAP’s Documentation project team will be happy to help you with the prose.
General guidelines for all documents
-------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Use standard American English and spelling
- Use consistent terminology
- Write in the active voice, using present simple tense when possible
@@ -42,13 +42,14 @@ General guidelines for all documents
- Use a spell checker
Abbreviations and acronyms
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
- Write out the term the first time it appears in the document, immediately followed by the acronym or abbreviation in parenthesis. Then use the acronym in the rest of the document. In diagrams, if space allows, write out the full term.
- Use “an” before an acronym that begins with a vowel sound when spoken aloud; use "a" before an acronym that begins with a consonant sound when spoken aloud.
-+ Examples: an MSO component, a LAN, an L3-VPN
+ + Examples: an MSO component, a LAN, an L3-VPN
+
ONAP terms
-----------
+^^^^^^^^^^
- AA&I vs AAI: AAI should be used.
- APP-C vs APPC: APPC should be used.
- SDN-C vs SDNC: SDNC should be used.
@@ -59,19 +60,20 @@ ONAP terms
- run time (noun). Example: "logging of events at run time".
GUI elements
-------------
+^^^^^^^^^^^^
- In general, write menu names as they appear in the UI. For example, if a menu or item name is all caps, then write it all caps in the document.
Headings (Titles)
------------------
+^^^^^^^^^^^^^^^^^
- Use brief, but specific, informative titles. Titles should give context when possible.
- Use sentence-style capitalization; do not end with a period or colon.
- Use a gerund to begin section titles. Examples: Configuring, Managing, Starting.
- Use descriptive titles for tables and figures titles. Do not number tables or figures. Do not (in general) add titles for screen shots.
Tasks
------
+^^^^^
- Start task titles with an action word. Examples: Create, Add, Validate, Update.
- Use [Optional] at the beginning of an optional step.
- Provide information on the expected outcome of a step, especially when it is not obvious.
- Break down end-to-end tasks into manageable chunks.
+