Skip to main content
Version: 2.2

Bricks Documentation Guidelines

When a brick documentation is written, here are a few guidelines so that the end result remains consistent with the rest of the platform bricks.

  • Within the documentation, text can be formatted using the Markdown syntax.
    The Markdown Cheat Sheet provides a good summary to get started. Adding New lines: to end a line and add a new one, you can end a line with two or more spaces, then type return.

  • Break down the text for the description into sentences. Preferably short ones.

  • Use punctuation to separate your thoughts: commas, full-stops...

  • Write the word Example on a separate line.
    Do not put it at the end of the sentence.
    Add a colon : after the word Example.
    Here is an example with the Concat brick:

    new And what the source text looks like:

    new

  • Bold the words that need the user's attention e.g. the word "Example" mentioned above.

  • Write descriptions for each input/output/property/event. Even a short one will do. Avoid the No description available gaps in the documentation as much as possible. It will greatly help with brick usage adoption.

  • Always provide clean examples.

  • Make notes/remarks about typical implementations and known issues.

  • Do not add new lines inside the properties or i/o descriptions. This will break the formatting. Always double check the end result to make sure it is visually ok.

  • Do not use mathematical signs as synonyms to normal words.
    For instance, instead of = use is or equals, instead of < use smaller or equivalents, etc...
    Avoid writing this, when the value = true, and prefer writing when the input value is true.

  • Write sentences in full english using subject & verbs without any contraction to avoid any confusion or misunderstanding e.g. it is computed, instead of it's computed, or The logic loops on a condition. instead of Loop on a condition.

  • When referencing links within the documentation, make sure that they open in a separate browser tab by using the following syntax:
    <a href="https://www.markdownguide.org/cheat-sheet/" target="_blank">Markdown Cheat Sheet</a>

    This ensures that the user doesn't leave DRAW when clicking on a link that opens the url within the current browser page when the following syntax is used:

    [Markdown Cheat Sheet]( https://www.markdownguide.org/cheat-sheet/)