jamesshore
commented
8 years ago I would love to have better documentation. Whatever approach we use, though, needs to fit two criteria:
- [ ] The documentation must be at least as high-quality, from a content perspective, as the existing hand-rolled documentation. In particular, all the cross-references and extra notes (such as compatibility notes) need to be preserved. Also, the unique format we use for descriptors would need to be preserved.
- [ ] From a workflow perspective, it must be at least as easy to create and edit documentation as it is now, and the code must be at least as easy to navigate and maintain.
I'm particularly concerned that auto-generated documentation will reduce quality. For example, when working with the Ember documentation, I found it very difficult to navigate, as it was obviously machine-generated and made it hard to find key concepts.
A partially automated approach might work--for example, we could automate the top-level API docs (QFrame, QElement, etc.) and keep a hand-generated approach for the descriptors.
JSDoc can be used to generate offline documentation. There is a tool for compiling JSDoc to HTML that is actively developed. There are libraries like jsdoc-to-markdown that build on the jsdoc3 compiler and make it target Markdown. Not sure how well that works, but it may be an option to building the Quixote docs which you prefer to be available in markdown.
Needs discovery, is this a good idea?