These are just some notes that I'm keeping track of as I consider rewriting the docs module.
Current Documentation Deficiencies
There hasn't been much change in the Enunciate-generated documentation mechanism since the very first release in Enunciate. To some degree, that speaks to it's general effectiveness and success, but I also worry about stagnation. There are some specific areas of focus that I think need to be considered
- Usability - Generated documentation should be easy and natural to read and navigate
- Tooling and Standards Support - Enunciate should leverage as much as possible existing tools and industry standards for documentation.
I worry that the existing documentation mechanism falls short in each of these areas:
Documentation functionality and features should be easy to extend and configure.
Generated documentation should be easy and natural to read and navigate. The original documentation mechanism was designed for service-oriented APIs and resource-oriented APIs have become much more popular, at least for public WS APIs. The REST documentation seems a bit clunky to navigate. You have to do it by URI path, there's no great way to group endpoints into logical sections, and you just don't get enough context about the input and output parameters when reading about specific resources and operations. It's also hard to understand the implications of all the available media types.
Tooling and Standards Support
Enunciate could do a better job of leveraging existing tools and standards for generating documentation. When you consider features like internationalization, templating and even just being able to customize the look-and-feel of the documentation, it would be much better for Enunciate to be able to pass that off to other tools and standards.
- What if Enunciate generated a DocBook document?
- Somehow allow users to inject custom DocBook tags?
- Perhaps provide some Enunciate-custom DocBook XSLT?
Things to Watch Out For
We want to be careful not to throw out the good things that Enunciate has done with the documentation.