search

redwoodjs / redwood

The App Framework for Startups
https://redwoodjs.com
MIT License
16.93k stars 973 forks source link

Organizing the docs #4921

Open jtoar opened 2 years ago

jtoar commented 2 years ago

According to the sidebar on the website, right now we have three kinds of docs: references, tutorials, and cookbooks.

The references section is organized alphabetically by concept: assets and files, graphql, security, etc. Ordering things alphabetically makes for fast look up, but we’re not writing a dictionary. There’s definitely a better way.

The way we organized the docs was mostly a matter of pragmatism: at the time we prioritized writing content, and that was the right move. So now that we’re feature complete, we should consider reorganizing things.

This is a huge task, so besides thinking about it carefully, we’ll have to carry it out in stages. The most actionable item is probably adding a call to action to the docs/index page.

Note that these notes are from my discussion with @peterp. Another thing we found useful is classifying the information in each reference doc. Some reference docs really are just references, but others--like testing--are more like tutorials. Another actionable item here is to use docusaurus’s tagging functionality to codify this, though there's many ways we could go about it.

cannikin commented 2 years ago

I moved Quick Start to the top of Reference, figured that might help new people a bit!

rkmitra1 commented 2 years ago

Not sure if this is the correct place for my comments. I miss the old Tutorial sidebar where you saw all the pages at once. With the new docusarus implementation and chapters, a user will have to open each chapter individually to see the breadth of RW's great tutorial.

Suggestions:

  1. Would it be possible for there to be a button that expands ALL the chapters at once. Reference down arrow opens to all pages. Could a tutorial down arrow (double arrow?) be added that would open all the chapters.

  2. Alternatively, would there be a a way to add a tutorial index like a book chapter index so a user could see all the chapter pages at once.

My notes:

  1. I believe that lots of people will not go through the tutorial in one sitting. Displaying all the pages will let them restart mid-point very easy.

  2. Seeing the full index of the tutorial pages is really a great way for newcomers to get an overview of all that RW offers.

I have been using and enjoying Redbook for a long time. As such I have gone through the tutorial MANY times.