<<Matthew Harffy - 18/08/2017: I think this draft can now be deleted as I have copied the content in an edited form into the formal documentation. I have also updated the old Style Guide on the wiki.>>

This style guide is for ONAP documentation contributors and reviewers.

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?

TODO: <<add links to Documentation process/automated tools sections>>

What kind of documents are required?

This depends on your project output, but here is a list of standard and common documentation:

• Installation Guide

• End-user guide (this includes GUIs, and may include user and admin role details)

• Command Line Interface Guide

• API Guide

• <<TODO: Determine other types of documentation>> 

Markdown conventions

TODO: <<establish markdown guidelines for headings, lists, tasks, GUI labels, etc.; provide external links for learning>>

Writing guidelines

Following these writing guidelines will keep ONAP documentation consistent and readable.

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

• Write objective, professional content

• Keep sentences and paragraphs short and clear

• 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

ECOMP terms

• AA&I vs. AAI: Both are allowed in Release 1, but use AAI from now on.

• APP-C vs APPC: Both are allowed in Release 1, but use APPC from now on. 

• SDN-C vs SDNC: Both are allowed in Release 1, but use SDNC from now on.

• Heat vs HEAT: Both are in use. The official website uses "Heat", but HEAT prevails in reference documents.

• life cycle vs lifecycle or life-cycle: prefer two words "life cycle", as recommended here, and because OpenECOMP contains a Life Cycle Management (LCM) functionality. Note that Reference documents, such as <<DocRef: "Common Requirements for Virtual Network Functions">> show both forms. 

• onboarding:

  • taking a Virtual Network Function (VNF) from a source or supplier and integrating it into the OpenECOMP platform

  • (avoid this usage) telling a potential developer/contributor what they need to know about tools, policies, processes, etc. to start using or contributing to Open ECOMP. Instead, use a title such as "Developer Starting Guide" rather than "Developer Onboarding Guide".

• open source (adjective): capitalize only in titles; avoid "open-source". (Based on prevalence on the web.)

• orchestration: The coordination of facilities and lower-level services in a software-defined networking context to define and provide higher-level services

• recipe: use alternatives like "workflow and configuration information", when related to a Resource, Service, Product, or Offer. However, within the context of the server configuration system Chef, a recipe is the most fundamental configuration element.

• run-time vs. execution-time (adjective): prefer run-time. Example: "run-time logging of events"

• 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.