Any brick you produce is as good and useful, as clear & detailed its documentation is.
Note that a brick does not have to be shared or public to justify the effort to be documented. Any user including its own author will find value in such documentation for productivity and maintenance purposes.
For that matter, the
Spec & Doc tab allows the creation of any brick's documentation, where, the
Summary are defined, along with the documentation for all inputs & ouputs in case of an Action or a Function.
Example of a user facing brick documentation
Source version of this brick documentation
Desription & Summary as defined in the
Spec & Doc tab.
Source text for the input values.
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
Example. 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.
When naming a brick, name it with its actual name and quoted with single backticks
For instance, write this:
Use the `Get Object List` brick to retrieve the list from a data type
to render it like this
Get Object Listbrick to retrieve the list from a data type
When referring to the use of another brick, make sure that brick is available in a basic DRAW package or within the same package. In other words do not refer to a brick no one else has access to.
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.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/)