-
Notifications
You must be signed in to change notification settings - Fork 61
Concept docs: discussion
Brent Huisman edited this page Dec 7, 2020
·
2 revisions
Goal: Everyone in the team to be familiar with the full arbor concept docs and give feedback.
Questions:
-
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.
-
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.
-
Is there any missing information?
-
Does the existing information flow well?
-
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.
-
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.