Skip to content

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:

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

  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.