Headings
The highest level is Heading 1
It is OK to have a singleton Heading at any level
Do not use a Heading (n+1) unless it is under a Heading n
Capitalization
- First word on each line of a bulleted list (except for definitions in the Glossary)
- The following are proper nouns that in many cases have a specific meaning in OpenECOMP and should be capitalized:
- Letters in words that are part of acronyms. See Acronyms treatment, below. Examples:
- Business Support System (BSS)
- REpresentational State Transfer (REST)
- Open Platform for NFV (OPNFV)
Usage
ingredients: avoid
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".
orchestration: The coordination of facilities and lower-level services in a software-defined networking context to define and provide higher-level services
recipe: try to avoid - use alternatives like "workflow and configuration information", when related to a Resource, Service, Product, or Offer
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"
subsystem: a large component; avoid "module" when referring to OpenECOMP subsystems such as MSO
Other
Acronyms: Write out in first instance on a page, immediately followed by the acronym in parenthesis. Then use the acronym on the rest of the page. In diagrams, if space allows, use full name. Example: Operational Support System (OSS). For plurals, add an "s" but do not use "es", such as OSSs. (This is how it's done in OpenECOMP.pdf.)
Use of "&": Do not use unless in "AT&T." Some components of OpenECOMP have titles that in original source documents use the "&" in their acronymic abbreviation, but most do not. (Example: A&AI). For consistency, exclude from such an acronym, e.g. A&AI becomes AAI.
Incomplete items: Denote text that requires additional work using "<<" (easily searchable) and preferably italics:
<<Link to security-related APIs here>>
Replace "&" with "and", except for acronyms such as A&AI, OA&M
<<TBD: fonts/indications of code, user input, system output>>
Figure numbering and labeling - start with Figure 1 on each page
Foreign phrases and abbreviations (avoid, and what to substitute)
-e.g. > for example, such as
- i.e. > that is (or rephrase)
- via (through, or sometimes by)
if you DO use "e.g." and "i.e.", use commas after these
quote marks - avoid <<can we drop this? We're using quote marks on this page, and we need to.>>
Try to keep sentences 25* words or less. If very lengthy, consider rephrasing and breaking into a bulleted list.
* Sometimes impossible but worth shooting for.