Support the complete documentation effort

[RaySinnema]

See the discussion in the wiki.

[jonathanrobie]

RADL already allows documentation to be written in a foreign vocabulary like Docbook or HTML5 as long as the content is well formed. To me, it would make more sense to allow front matter and appendices, which could include whatever a documentation team wants.

I'm uncomfortable with the idea of a highly structured schema for this purpose. Providing this level of structure for a REST API description makes sense, because an API is highly structured. I think industry experience has shown that less structured formats like Docbook and DITA win out in the field of technical documentation like user manuals.

RADL is for API descriptions, and supporting additional documentation in the API description makes all kinds of sense. Using RADL for something like a Getting Started Guide is like using a bagpipe for a screwdriver.

[RaySinnema]

I'm uncomfortable with the idea of a highly structured schema for this purpose.

I did not propose that idea. In fact, I didn't propose anything. I just wrote down what I think should be the complete documentation set for an API, so that we could talk about it and see what, if anything, needs to be done in RADL to support it.

[jonathanrobie]

OK. Let me take each of these components and say something about the relationship I think it has to RADL.

• Getting Started Guide: no direct relationship to RADL. You can write this with whatever tool you want.
• Collection of Common Use Cases: I imagine this code is written by hand, and a given use case may involve any number of states and transitions. I don't see this as being written in RADL or generated from RADL.
• API Reference Manual: This is what RADL is for. Support for front matter, appendices, etc. would be helpful for more complete documentation. As you point out, search and the ability to try out the API interactively would be great additions. The latter requires us to link the API docs to a running implementation, something we have not yet done.
• Administrator's Guide: No relationship to RADL.

Currently, RADL is static HTML, and we do not have a well defined relationship between documentation and a running instance.

[gentlewind]

I agree with both of you. The wiki page covers the main documentation lifecycle. Other documentation types could be tutorials, whitepapers or reference implmentations which give developers a step-by-step guide on using the system and its ecosystem technologies to build a solution for a particular scenario.

The API reference Manual usually needs to be categorized into several different sections if it is large, e.g. (content APIs, security APIs, etc.).

The RADL user documentation can do a better job in the area of API Reference Manual. One problem is the rendered HTML page for RADL documentation could be super large (take Documentum extended REST Services as an example) and is not easy for read, especially for the overview of its state transition.