Skip to end of metadata
Go to start of metadata
Icon

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

  1. Extensibility
  2. Usability - Generated documentation should be easy and natural to read and navigate
  3. 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:

Extensibility

Documentation functionality and features should be easy to extend and configure.

There just isn't a great way for users to add custom hooks or analytics tracking or things like that without having to update a nasty XSLT stylesheet.

Usability

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.

Ideas

  • 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.

  • No labels