Concept docs: discussion

Goal: Everyone in the team to be familiar with the full arbor concept docs and give feedback.

Questions:

1. Will a new user reading the concept pages without going through the API understand the main ideas and concepts of Arbor?

   • Brent: The individual concepts are described pretty well, but how they fit together is only very briefly and high-levelly mentioned. I would appreciate a bit more elaboration here. A good example is Sams explanation of why cell description and kind are separate A more recent example was this discussion about mechanisms and catalogues. I'd like to see much, much more of that. The diagrams I have in mind are a possible way of addressing this.

2. Are any of sections particularly confusing, misplaced or unnecessary?

   • Brent: we need a nomenclature/glossary page.
   • Brent: we could point out differences with Neuron wherever relevant. Maybe we can limit this to the glossary page?
   • Brent: probes/stimulus page is coming?
   • Brent: discretisation page?
   • Brent: Cell Mechanism concepts page: include listing of default mechanisms, their name/tag and description, enumeration of parameters and their role/meaning/explanation wherever not absolutely trivial. Is a bit API-y, but let's discuss where.
   • Brent: we need a page on file formats support. Is not a concept, but
   • Brent: developer concepts, or architecture overview, could be added, but may be better placed under /internals.

3. Is there any missing information?

4. Does the existing information flow well?

5. Are there enough or maybe too many links?

   • Brent: I like links and I cannot lie. It's hard to scan for links right now, which is a problem with markup of the rtd theme (no underline, nearly same color as emphasis. Highly in favor of switching theme and markup style to something a bit more accesible.

6. Opinions on the docs in general.

   • Brent: The contribution-pr has a howto-doc page. We can add to it as we have the above discussion.