Improve website documentation navigation

I think we need a discussion on documentation organisation for the website. For me, the way things are currently laid out is very confusing and I have an incredibly hard time finding stuff.

The most important aspect of a good documentation is to divide things in as few as possible “conceptual” chunks. Above 4 or 5, everyone gets lost. It’s easy to think “ah OK, this thing is about state, view and mutations”, it is much harder if you have “State, Components, Signals, Action, Operators, Factories, Paths, Compute, Routing, etc”.

So here is a proposition that everyone is welcome to edit and alter.

Conceptual structure

+ cerebral documentation (single entry at the top)
  + [themes] (getting started, state, view, mutations) <=== not more the 4 or 5 entries here !!
    - starts with written presentation (no deep detail, not exhaustive api)
    - api for each element in them (Signal, Action, operators for "mutations" for example).
      this means that if I go to "state", I should find everything, not missing information on state paths, etc
    - themes are presented trying to avoid introducing too many concepts at a time = simplest things first
  + guide
    + chapter
      - should have next and previous buttons
      - should have links to precise docs in [themes]
  + other packages (≠ cerebral)

Actual structure

(work in progress: edited from feedback)

+ Guide
  + Get started <====== Can go here
  + Setup and tooling
    - install
    - we see how to setup controller without too many details
    - short intro du developer tools
    - present controller, modules
  + State and mutations
    - we present what the state is and what a state path is
    - we present how mutations are handled, introducing operators
    - Signal, Action, operators, providers
  + Views
    - we present how views depend on state and how they update
    - connect, tags
+ API
  - single page with elements organised with chapters similar to "guide"
  + packages <===== Can go here

[christianalfoni]

Hehe, good point 😃

Yeah, I agree packages really is API. Though do you mean having cerebral and current content of API under that, or just list packages at the bottom of current API?

I think also a confusion is having “guide and API”, like the idea of current “Developer guide” is: “The first time you go to the site and dive into Cerebral”. If we call it “Developer guide” or just “Guide”, you would be tempted to look there later… which I think was one of your frustrations?

What about this, summarized:

• Introduction
  • The architecture
  • Install
  • Choosing a view type
  • Debugger
  • … the rest in “Developer guide”
• API
  • Cerebral
    • What is now in API
  • … rest of what is in “packages”
• Resources
  • In detail articles
  • Projects
  • Videos
  • Migration guide
  • Example 1
  • Example 2

?

[christianalfoni]

@hipertracker Hi and thanks for writing up your thoughts 😃

I really like this structure, though we are lacking the resources to make the design real and also right now people are starting to burn out a bit getting Cerebral released.

I think we should keep this as a reference for when we ever get a hold of a webdesigner and we have built up some new energy after release to put efforts into restructuring and writing more docs 😃