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
Exampleon a separate line.
Do not put it at the end of the sentence.
Add a colon
:after the word
Here is an example with the
And what the source text looks like:
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 availablegaps 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
equals, instead of
smalleror 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/)