continuing conversation from #310
There's not much separation currently between docs meant for using Redwood (e.g. building apps) and those for developing Redwood. Currently, docs lives within either the /redwood repo or /create-redwood-app repo. The rwjs.com site has a list of docs to parse, gets them, and displays on the site. So depending on which context you're accessing docs, it can be a bit unclear what they're meant for. And even more unclear when we combine both types of docs into one.
Secondly, our current yarn rw help output isn't all that informative or helpful (yet). I super ❤️ adding the completion shortcuts #311 but we still need to add/improve help text.
Thirdly, it seems very standard for library/framework documentation to contain cli command-specific docs. And for our project where we'll be increasingly leaning into cli, it will be a necessity and also an entry point for understanding the Redwood approach. We're learning through feedback about our site and tutorial that people definitely experience the quality of this project as a whole, including the code + documentation as a single unit of evaluation.
Examples
Examples of full cli documentation:
Example of "point users to help" cli documentation:
Discussion
All that said, yes, keeping up with docs is hard work in a rapidly evolving framework. We'll need to allow for things to get behind and be a bit messy. But we should also be thinking toward how we can improve processes so we can collaboratively keep things in sync (e.g. maybe a PR template checklists, etc.)
And I also think we're pushing up against our current system of not having a tool to manage/generate documentation from one place (e.g. Docz, etc.). So maybe it's time to evaluate that as well.
Could you all please add some comments here for discussion? I don't mind if the topics wonder a bit from CLI specificity as long as we are addressing the general topic of documentation and how to both build a foundation and set a direction + vision.
Thanks!
continuing conversation from #310
There's not much separation currently between docs meant for using Redwood (e.g. building apps) and those for developing Redwood. Currently, docs lives within either the /redwood repo or /create-redwood-app repo. The rwjs.com site has a list of docs to parse, gets them, and displays on the site. So depending on which context you're accessing docs, it can be a bit unclear what they're meant for. And even more unclear when we combine both types of docs into one.
Secondly, our current
yarn rw helpoutput isn't all that informative or helpful (yet). I super ❤️ adding the completion shortcuts #311 but we still need to add/improve help text.Thirdly, it seems very standard for library/framework documentation to contain cli command-specific docs. And for our project where we'll be increasingly leaning into cli, it will be a necessity and also an entry point for understanding the Redwood approach. We're learning through feedback about our site and tutorial that people definitely experience the quality of this project as a whole, including the code + documentation as a single unit of evaluation.
Examples
Examples of full cli documentation:
Example of "point users to help" cli documentation:
Discussion
All that said, yes, keeping up with docs is hard work in a rapidly evolving framework. We'll need to allow for things to get behind and be a bit messy. But we should also be thinking toward how we can improve processes so we can collaboratively keep things in sync (e.g. maybe a PR template checklists, etc.)
And I also think we're pushing up against our current system of not having a tool to manage/generate documentation from one place (e.g. Docz, etc.). So maybe it's time to evaluate that as well.
Could you all please add some comments here for discussion? I don't mind if the topics wonder a bit from CLI specificity as long as we are addressing the general topic of documentation and how to both build a foundation and set a direction + vision.
Thanks!