Bricks Documentation

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 Description & 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 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:

  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

  Use the Get Object List brick 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 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.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/)