Skip to main content

Documenting Software

The following pages define the minimum standard of developer documentation required within an Overture project, which include:

  1. A Readme.md file.

  2. A /docs folder with the following basic structure:

    .
    └── docs/
        ├── 01-Overview/
        │   └── 01-Overview.md
        ├── 02-Setup.md
        └── 03-Guides/
            ├── 01-Usage.md
            ├── 02-Development.md
            └── 03-Deployment.md
    tip

    To ensure your folders and files are ordered correctly in the sidebar use the numbered naming convention seen above.

  3. A CONTRIBUTING.md file

  4. A code_of_conduct file

  5. A license.md file

Markdown formatting​

When adding and editing markdown files within the project repository there are a few considerations to be made to ensure your files get rendered correctly by docusaurus:

  • The top level heading (ex. # Top Title) will be used by docusaurus for the sidebar label

  • Docusaurus supports codeblocks, tabs, dropdowns and admonitions.

    Using Codeblocks
    • Always reference the language being used
    • When appropriate use the following syntax to reference the source:

      • markdown title="website/docs/04-standards/03-guides.md"

    website/docs/04-standards/03-guides.md
    # The title value renders out the code block with the path provided

  • Include callouts for important information using these styles:

    tip

    Helpful Tips Provide additional insights or shortcuts

    caution

    Important Notes Highlight crucial considerations or potential pitfalls

    info

    Additional Context Provide supplementary information that adds value

  • If your page shares the same name as a folder, you can use the DocsCardList component to automatically display card-style links to all files contained within that folder:

  • Use dropdowns to condense the page and hide optional or supplemental content

    Click here for the markdown code used to write the above examples
    ## Markdown formatting 

    When adding and editing markdown files within the project repository there are a few considerations to be made to ensure your files get rendered correctly by docusaurus:

    - The top level heading (ex. # Top Title) will be used by docusaurus for the sidebar label

    - Docusaurus supports codeblocks, [tabs](https://docusaurus.io/docs/markdown-features/tabs), [dropdowns](https://docusaurus.io/docs/markdown-features#details) and [admonitions](https://docusaurus.io/docs/markdown-features/admonitions).


        :::tip[Using Codeblocks]

        - Always reference the language being used
        - When appropriate use the following syntax to reference the source: 
            -  `markdown title="website/docs/04-standards/03-guides.md"`


        ```markdown title="website/docs/04-standards/03-guides.md"
        # The title value renders out the code block with the path provided
        ```
        :::

    - Include callouts for important information using these styles:

        :::tip
        **Helpful Tips**
        Provide additional insights or shortcuts
        :::

        :::caution
        **Important Notes**
        Highlight crucial considerations or potential pitfalls
        :::

        :::info
        **Additional Context**
        Provide supplementary information that adds value
        :::

    - If your page shares the same name as a folder, you can use the DocsCardList component to automatically display card-style links to all files contained within that folder. This creates a dropdown-style navigation menu.

    <DocsCardList />

    <details>
    <summary>**Click here for the markdown code used for the above examples**</summary>
    [The content seen in this dropdown would go in here]
    </details>

Images & Diagrams​

Images and diagrams can be valuable, but they can take lots of time and require maintenance. When using images or diagrams, consider how beneficial the visualization will be and how frequently you need to update it.

Writing Guidelines​

Language​

We use Canadian English (en-CA) as our standard language for all written and verbal communication.

Use an Active Voice​

The active voice is concise and more accessible for readers to comprehend. Active voice is naturally used in conversation and therefore, readers understand and engage more with writing in the active voice.

👎 Disengaging👍 Engaging
The developer environment has been set up successfully.We have successfully set up the developer environment.
The necessary tools and dependencies are being installed.We are installing the necessary tools and dependencies.

Put Conditional Clauses First​

Put conditional clauses up front in sentences. With conditional clauses upfront, readers can skim or skip information they do not require. If done consistently, this saves significant time reading irrelevant information.

👎 Slow👍 Skimmable
See How to Use the Score Client for more informationFor more information, see How to Use the Score Client.
Set the analysis state to published, this will enable the analysis to be indexedTo index the analysis, set the analysis state to published

Write Accessibly​

Take note of how you describe software behaviours or user actions. Each reader will have a unique background and familiarity with the content, so avoid using language that assumes knowledge.

👎 Sets expectations that can lead to frustration👍 No assumptions, made reader friendly
Start by simply entering the following commandStart by entering the following command
To easily interact with our API see the Song Swagger UITo interact with our API see the Song Swagger UI

Whenever possible, also include descriptive links to prerequisite or contextual material. Our services benefit a variety of people and data; therefore, experience levels and fields of expertise can vary significantly from user to user.

Formatting & Punctuation​

Headers​

Use level 1 headers at the top of the page and divide your document using the lower level headers for subsections.

  • Capitalize the first word of a title or subtitle, even if it is a little word like "The" or "A."
  • Capitalize the first word after a colon and dash (ex., "Self-Report" instead of "Self-report").
  • Capitalize words of four letters or more (e.g., "With," "Between," and "From").
  • Except for the above rules, lowercase minor words that are three letters or fewer in a title or subtitle.

Numbered lists vs bulleted points​

  • Numbered lists for sequential items
  • Bulleted points for all other lists

Commas​

Use an Oxford comma for a list of three or more items.

Can lead to confusionClearer separatation
I had eggs, toast and orange juice for breakfast.I had eggs, toast, and orange juice for breakfast.

UI/Navigation Elements​

When referencing UI elements, have them in Bold

  1. Click Documentation > Get Started.
  2. Select Pre-Configuration Setup.