Writing docs#

A great way to contribute without writing code is to help writing documentation. Please reach out before contributing as the software is still in an alpha state and portions may not be worth documenting as it changes too frequently.

Writing technical documentation#

All documentation is written in ReStructured Text and is available in the BlenderBIM Add-on docs directory.

You can link to external websites. You can also link to sections on the same page, like Writing technical documentation. You can link to other pages, like Hello World or sections within other pages, like Unstable installation. We have autosectionlabel enabled so it is not necessary to manually create labels.

The following colours and annotation styles should be used for annotating images. All stroke widths are 3px with a corner radius of 3px. Horizontal underlines are 5px with a corner radius of 2px. The dark green is 39b54a and the light green is d9e021.

../_images/documentation-style.png

Special keywords such as Technical Terminology that the user should be aware of should be bolded, titlecased, and used consistently. You may use italics to emphasize words or phrases. Inline code must be quoted and longer code snippets may use code blocks.

$ cd /path/to/blenderbim
$ ls

Be sure to specify the language to enable syntax highlighting.

print("Hello, world!")

A button may be used to point users to a critical sample file or download.

You can use bulleted lists:

  • Like.

  • This.

Or ordered lists:

  1. Like.

  2. This.

Note

Instead of writing “Note that XYZ …” you should use notes sparingly to highlight “gotchas”.

Tip

Tips may be used to add a useful but optional suggestion.

Warning

Warnings may be used to highlight common mistakes.

See also

See also blocks should be used to reference further reading links.

Tables can be very annoying to format. You can use a CSV table instead.

Foo

Bar

Baz

ABC

01

02

DEF

03

04