{"type":"doc","content":[{"type":"paragraph","content":[{"text":"<>","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"This style guide is for ONAP documentation contributors and reviewers.","type":"text"}]},{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"efda9bf0-6dee-4c12-b57d-3cdce78bff33"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}}}},{"type":"heading","attrs":{"level":1},"content":[{"text":"Getting started","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When is documentation required?","type":"text"}]},{"type":"paragraph","content":[{"text":"All ONAP project contributions should have corresponding documentation. This includes all new features and changes to features that impact users.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"How do I create ONAP documentation?","type":"text"}]},{"type":"paragraph","content":[{"text":"TODO: <>","type":"text","marks":[{"type":"em"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"What kind of documents are required?","type":"text"}]},{"type":"paragraph","content":[{"text":"This depends on your project output, but here is a list of standard and common documentation:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Installation Guide","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"End-user guide (this includes GUIs, and may include user and admin role details)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Command Line Interface Guide","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"API Guide","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"<> ","type":"text","marks":[{"type":"em"}]}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Markdown conventions","type":"text"}]},{"type":"paragraph","content":[{"text":"TODO: <>","type":"text","marks":[{"type":"em"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Writing guidelines","type":"text"}]},{"type":"paragraph","content":[{"text":"Following these writing guidelines will keep ONAP documentation consistent and readable.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"General guidelines for all documents","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use standard American English and spelling","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use consistent terminology ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Write in the active voice, using present simple tense when possible","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Write objective, professional content","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Keep sentences and paragraphs short and clear","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use a spell checker","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Abbreviations and acronyms","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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. ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Examples: an MSO component, a LAN, an L3-VPN","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"ECOMP terms","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"AA&I ","type":"text","marks":[{"type":"strong"}]},{"text":"vs.","type":"text"},{"text":" AAI","type":"text","marks":[{"type":"strong"}]},{"text":": Both are allowed in Release 1, but use AAI from now on.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"APP-C","type":"text","marks":[{"type":"strong"}]},{"text":" vs","type":"text"},{"text":" APPC","type":"text","marks":[{"type":"strong"}]},{"text":": Both are allowed in Release 1, but use APPC from now on. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SDN-C","type":"text","marks":[{"type":"strong"}]},{"text":" vs ","type":"text"},{"text":"SDNC","type":"text","marks":[{"type":"strong"}]},{"text":": Both are allowed in Release 1, but use SDNC from now on.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Heat","type":"text","marks":[{"type":"strong"}]},{"text":" vs","type":"text"},{"text":" HEAT","type":"text","marks":[{"type":"strong"}]},{"text":": Both are in use. The official ","type":"text"},{"text":"website","type":"text","marks":[{"type":"link","attrs":{"href":"https://wiki.openstack.org/wiki/Heat"}}]},{"text":" uses \"Heat\", but HEAT prevails in reference documents.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"life cycle ","type":"text","marks":[{"type":"strong"}]},{"text":"vs","type":"text"},{"text":" lifecycle or life-cycle","type":"text","marks":[{"type":"strong"}]},{"text":": prefer two words \"life cycle\", as recommended ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"http://english.stackexchange.com/questions/68230/life-cycle-life-cycle-or-lifecycle"}}]},{"text":", and because OpenECOMP contains a Life Cycle Management (LCM) functionality. Note that Reference documents, such as <> show both forms. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"onboarding","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"taking a Virtual Network Function (VNF) from a source or supplier and integrating it into the OpenECOMP platform","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"(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\".","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"open source","type":"text","marks":[{"type":"strong"}]},{"text":" (adjective): capitalize only in titles; avoid \"open-source\". (Based on prevalence on the web.)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"orchestration","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"The coordination of facilities and lower-level services in a software-defined networking context to define and provide higher-level services","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"recipe","type":"text","marks":[{"type":"strong"}]},{"text":": 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 ","type":"text"},{"text":"the most fundamental configuration element.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#3f5364"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"run-time vs. execution-time","type":"text","marks":[{"type":"strong"}]},{"text":" (adjective): prefer run-time. Example: ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"\"run-time logging of events\"","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"run time","type":"text","marks":[{"type":"strong"},{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":":(noun) Example: \"logging of events at run time.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"GUI elements","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Headings (Titles)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use brief, but specific, informative titles. Titles should give context when possible.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use sentence-style capitalization; do not end with a period or colon.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use a gerund to begin section titles. Examples: Configuring, Managing, Starting.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use descriptive titles for tables and figures titles. Do not number tables or figures. Do not (in general) add titles for screen shots. ","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Tasks","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Start task titles with an action word. Examples: Create, Add, Validate, Update.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use [Optional] at the beginning of an optional step.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Provide information on the expected outcome of a step, especially when it is not obvious.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Break down end-to-end tasks into manageable chunks.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"type":"hardBreak"}]}]}]}],"version":1}

Browser not supported