Versions Compared

Old Version 17

changes.mady.by.user Unknown User (rnnavarro)

Saved on

compared with

New Version 18

changes.mady.by.user Unknown User (fay)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

(DRAFT: Currently this is a mostly a list of possible topics; any style rules are suggestions and not yet agreed to.)

Headings

The highest level is Heading 2; never use Heading 1. Why? Because we like smaller headings...

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
  • The following are proper nouns that in many cases have a specific meaning in OpenECOMP and should be capitalized:
    • Application Controller
    • Infrastructure Controller
    • Network Controller
    • Offer
    • Product
    • Resource
    • Service (note: use "service" in generic contexts; use "Service" for a Service Design & Creation tool object)
  • "Order Lifecycle Management"? <<NN>>
  • BSS (Business Support System) and OSS (Operational Support System) - these are standard telecomm industry terms. See Acronyms treatment, below.

  • Lowercase:  "service" "service request" "controllers" (when referring to the explicit 3 in list above, write them out as above. You can say "Application, Infrastructure, and Network Controllers" if you are mentioning all 3 of them at once (likewise for 2 of them) 

...

  1. taking a Virtual Network Function (VNF) from a source or supplier and integrating it into the OpenECOMP platform
  2. (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".

recipe: OK to use this term to describe workflow and configuration information related to a Resource, Service, Product, or Offer

...

if you DO use "e.g." and "i.e.", use commas after these

Heading usage (use built in heading defaults that come with Confluence)
  - Make sure that they come in sequence, that is, don't just put a 3rd level heading in because "it looks right"-there has to be a 2nd level heading before it.

quote marks - avoid

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.

treatment of certain keywords like “project” (OSS vs. customer vs. ?) (BILL: I am not sure here what this means; please elaborate)

prefer run-time to execution-time (adjective)