Directory Structure
Each component should have a docs folder with a minimum of:
Required Files
index.rst
is the table of contentsrelease-notes.rst
contains the release notes for the componentdeveloper-guide.rst
contains information that a developer needs to know in order to work on the component- this should be very technical, aimed at people who want to help develop the components
- this should be how the component does what it does, not a requirements document of what the component should do
- this should contain what language(s) and frameworks are used, with versions
- this should contain how to obtain the code, where to look at work items (Jira tickets), how to get started developing
api-docs.rst
contains details on the component’s API
Optional Files
#. user-guide.rst
contains information on how to use and configure the component; most components will not have a user guide
- if the guide contains sections on third-party tools, is it clearly stated why the ORAN-OSC platform is using those tools? are there instructions on how to install and configure each tool/toolset?
- does the guide state who the target users are? for example, modeler/data scientist, ORAN-OSC platform admin, marketplace user, design studio end user, etc
- if there are instructions, they are clear, correct, and fit for purpose
- does the guide contain information more suited for a different guide?
- a user guide should be how to use the component or system; it should not be a requirements document
- a user guide should contain configuration, administration, management, using, and troubleshooting sections for the feature.
Templates
Templates are available in the documentation project under docs/docs-contributor-guide/templates. You can clone the documentation project or download the templates from Github.
Current list of templates:
- api-docs.rst | rendered
- developer-guide.rst | rendered
- index.rst | rendered
- install-guide.rst | rendered
- release-notes.rst | rendered
- user-guide.rst | rendered
The templates themselves also contain guidance on what topics to include in the contents. Please read the contents of the templates!
Writing Guidelines
Following these writing guidelines will keep ORAN-OSC documentation consistent and readable. Only a few areas are covered below, as we don’t want to make it too complex. You can’t go wrong keeping things simple and clear.
Don’t get too hung up on using correct style. We’d rather have you submit good information that doesn’t conform to this guide than no information at all. ORAN-OSC’ Documentation project team will be happy to help you with the prose.
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 parentheses, i.e. ReStructuredText (RST). 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 RST file, a PMML file.
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
- Use capitalization; do not end with a period or colon
- Use a gerund to begin section titles if it makes sense. 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
Use the following to create the Document title:
- = with overline/underline
Use the following symbols to create headings:
- Section 1: * with overline/underline
- Section 1.1: - with underline
- Section 1.1.1: + with underline
- Section 1.1.1.1: ^ with underline
Consider rewriting the content if your document needs more than 4 levels of headings.
Non-Numbered Headings in RST
Below is an example of how to denote headings of various levels in RST.
See the Section Headers Example - No Automatic Numbering for how this renders in HTML.
================= H1 Document Title ================= *************** Section 1 Title *************** Section 1.1 Title ----------------- Section 1.1.1 Title +++++++++++++++++++ Section 1.1.1.1 Title ^^^^^^^^^^^^^^^^^^^^^ Section 1.1.1.1 Title2 ^^^^^^^^^^^^^^^^^^^^^^ Another Section at the 1.1.1 Level ++++++++++++++++++++++++++++++++++ How the Header is Underlined Makes all the Difference +++++++++++++++++++++++++++++++++++++++++++++++++++++ Section 1.2 Title ----------------- Section 1.2.1 Title +++++++++++++++++++ Section 1.2.2 Title +++++++++++++++++++ *************** Section 2 Title *************** *************** Section 3 Title ***************
Automatically Numbered Headings in RST
RST supports automatic numbering of sections. Place the sectnum directive at the top of your page. See the 1 Section Headers Example - Automatic Numbering for how this renders in HTML. Note that RST considers the Document Title to be the first Header and will number it!
================= H1 Document Title ================= .. sectnum:: *************** Section 1 Title *************** Section 1.1 Title ----------------- Section 1.1.1 Title +++++++++++++++++++ Section 1.1.1.1 Title ^^^^^^^^^^^^^^^^^^^^^ Section 1.1.1.1 Title2 ^^^^^^^^^^^^^^^^^^^^^^ Another Section at the 1.1.1 Level ++++++++++++++++++++++++++++++++++ How the Header is Underlined Makes all the Difference +++++++++++++++++++++++++++++++++++++++++++++++++++++ Section 1.2 Title ----------------- Section 1.2.1 Title +++++++++++++++++++ Section 1.2.2 Title +++++++++++++++++++ *************** Section 2 Title *************** *************** Section 3 Title ***************
If your guide has enough content, consider breaking it up into chapters, with one chapter per RST file. You will need to list each page in your index.rst. See Developer Guide with Automatically Numbered Sections for an example.
Task(s)
- 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.
Including Design Diagrams and Images
The developer-guide.rst template contains information and examples on how to incorporate design diagrams in your guide.