3 ms·
One of the best articles I've seen on writing documentation is "What Nobody Tells You About Documentation" [0]. It divides docs into four categories: Tutorials
by acemarke 7y ago
One of the best articles I've seen on writing documentation is "What Nobody Tells You About Documentation" [0]. It divides docs into four categories: Tutorials, How-To Guides, Discussions, and References.
I'm currently working on a major rewrite of the Redux core docs [1], and I've been taking notes on that post and various other docs writing resources [2] so I can apply them to the rewrite.
[0] https://www.divio.com/blog/documentation/ https://www.divio.com/blog/documentation/
[1] https://github.com/reduxjs/redux/issues/3592 https://github.com/reduxjs/redux/issues/3592
[2] https://github.com/reduxjs/redux/issues/3609 https://github.com/reduxjs/redux/issues/3609
- ampdepolymerase 7y agoDon't forget the "Quickstart". For example if you run a weather forecast/historical data API most people probably only want "how to get weather on X day" which should be up front and center. The rest of the options such as filtering or finer tuning comes later.
- acemarke 7y agoYeah, that's actually something I'm planning to add to the Redux docs shortly - a "Quick Start" tutorial page that shows things in a "top-down/how-to" approach (specifically using our new Redux Toolkit package [0] and the React-Redux hooks API [1]), vs the existing tutorial that teaches concepts "bottom-up". I started an initial attempt to write that page [2], wasn't happy with where it was going, and stepped back to do some analysis on other docs sites first so I could nail down how i want to tackle explaining things. I'm hoping to try writing that again after I get this next version of Redux Toolkit out the door. [0] https://redux-toolkit.js.org https://redux-toolkit.js.org [1] https://react-redux.js.org/api/hooks https://react-redux.js.org/api/hooks [2] https://github.com/reduxjs/redux/pull/3675 https://github.com/reduxjs/redux/pull/3675