...
- 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.
For buttons with images (or just clickable images with no box):
use the format "...click the <name> icon <image>."
or, use the format "...click the <name> icon." directly followed by an image showing the location of the icon in context, then use the inline <image> only for the rest of the task.
Headings (Titles)
- Use brief, but specific, informative titles. Do Since the docs are web-based, do not use generic titles (examples of generic titles: Overview, Introduction, Assumptions, Commands). Titles should give context when possible.
- Use sentence-style capitalization; do not end with a period or colon.Colons are allowed within a title; dashes, parentheses, and slashes are not.
- 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.
Lists
List items that are full sentences: capitalize the first letter and end with a period.
- List items that complete the stem sentence to create a full sentence: lowercase first letter and end with a period.
- List items that are not sentences: lowercase first letter, no period.
Note: Make exceptions for case-sensitive items that must be lowercase, such as commands.
Introduce a list with a stem sentence followed by a colon.
Generally, use a noun to end the introduction to a list. For example, " Configure <feature> using the following values:”.
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.Use “Click <icon>…” when referring to an action button on the GUI.
- Break down end-to-end tasks into manageable chunks.