search

onosproject / onos-docs

Consolidated documentation for the ONOS project.
https://docs.onosproject.org
4 stars 10 forks source link

Docs should be restructured at the top level in to 4 user oriented groups - Tutorials, Guides, Discussion & References #60

Open SeanCondon opened 5 years ago

SeanCondon commented 5 years ago

As proposed at the Engineering Meeting on 23rd October '19 documentation should be structured so that users can find what they want easily.

The discussion at https://www.divio.com/blog/documentation/

suggests that end user needs fall in to 4 categories

A lot of the existing pages can be categorized in to these groups, and the gaps in our documentation will become apparent when such a categorization is done. This can lead to further PR's - it does not all have to be done under this one

adibrastegarnia commented 5 years ago

@SeanCondon I agree. Do you think should we address it at navigation tree level (i.e. here in onos-docs) by categorizing docs or should we address it in each repo by categorizing docs there as well? There are tradeoffs for each.

SeanCondon commented 5 years ago

I think people looking for tutorials and how to guides would be on the aggregate level, but discussion could stradle the aggregate and individual. I think reference would mostly be at the individual project level.