Documentation¶
The source for the documentation is
found in the /doc subdirectory. You can add your contribution to the documentation
in the same way you would contribute code, please see the PR workflow section.
Todo
This page is under construction.
Update policy¶
How to we decide if documentation is good? By observing how effective it is used in practice. If a question on Arbor (regardless of medium) is satisfactorily resolved (on both sides!) by with a pointer to the (relevant section in the) docs, the documentation was good. If, on the other hand, explanation was needed, the documentation was bad.
If you found the documentation to be insufficiently clear or elaborate, you must consider this a bug and find or file an issue and if you are able, make a pull request.
Labels and filename conventions¶
Although it is not absolutely essential to do so, we try to keep to the following conventions for naming files and labels, with the goal of making it easy to construct one from the other such that you don’t have to remember or look anything up. We try to cross-link where we can, which means we label where we can, which translates to a large number of labels.
Wherever possible, observe:
file names: avoid underscores as much as possible. E.g. cpp/cable_cell.rst -> cpp/cablecell.rst.
page-level labels in each file: the path concatenated without spaces. E.g. cpp/cablecell.rst -> cppcablecell.
heading labels in a file: pagelevel-sectionname. Feel free to slugify long headings.
E.g. the morphology section in the C++ cable cell docs could be cppcablecell-morph.
Language¶
Although the primary language of Arbor is C++, we use English for most of the non-code. If in doubt, we recommend following the European Union’s English style guide.
In general we try to have a relaxed and concise approach to the language.