Support for the complete documentation lifecycle

This is a proposal from Ray. There is not yet consensus that RADL should support the entire document set - see https://github.com/restful-api-description-language/RADL/issues/48

Ideally, the documentation is divided into a couple of different modules, with decreasing levels of abstraction and increasing levels of detail. These different modules should address different stages in the developer's learning cycle:

• The Getting Started Guide should give a high-level overview of what the system is for and why the client developer may want to build a client for it. It should be as short as possible and contain links to more detailed documentation. It should tell the client how to perform one-time actions like acquiring an API key if the API requires one. Finally, it should describe how to build the simplest program that can work with the API, the equivalent of the infamous Hello, world! application.
• The next level is a Collection of Common Use Cases, with code examples that walk the client developer through the entire process from start to finish. The state diagrams form the basis of these descriptions.
• The Reference Manual should be complete and thorough, listing everything you will ever need to know about the API, like the HTTP methods and link relations to use, what error conditions may be encountered, etc. The Reference Manual should offer a search and/or index facility to quickly find the right location in the wealth of information that it contains. Ideally the Reference Manual should be interactive, like Swagger's Try it out! button.
• If the API is for a system that can be installed in multiple places, an Administrator's Guide is also needed. This document should explain how to install the system, how to configure it for secure use, how to scale it, etc. In short, it should contain all the information required for setting up the system and operating it properly.