-
Notifications
You must be signed in to change notification settings - Fork 68
Documentation Format Style Survey for VIAS
This survey was originally posted by @pkinney on github issue #85.
Since I think this is worthful information, at closin #85, I copy the survey to this Wiki.
@aShinjiroUrata
At the bottom of this comment, I've listed out a few of the possible options for adding varying levels of strictness on the format of the documentation. However, regardless of the format that we may choose to expose pieces or all of the documentation, I believe we need to generate a specification that W3C can publish and that follows those general patterns. This means a "static" version. We have the option to "export" some of the documentation in any number of more interactive formats, but will need the "core" static version first, I think.
To that end, I think we can decide on a content structure and some formatting details up front. I propose the following TOC for the specification (stealing a bit form the current Vehicle Information Access Spec):
- Introduction/Puprose/Overview
- Basic concepts
- What this spec describes
- What it means to be "compliant" (?)
- etc.
- Terminology
- Security and privacy considerations
- Data Model (reference the VSS or resulting spec)
- How the model is defined
- How to reference the model
- How to discover the model
- WebSocket
- Connection Setup
- Protocol Overview - who says what when
- Message Types
- subscribe
- unsubscribe
- get
- set
- ...
- Use Cases and Sample/Reference code
- HTTP
- Headers
- Routes
- GET /api/v1/...
- PUT /api/v1/...
- ...
- Use Cases and Sample/Reference code
For each message, we need to define:
- Description
- Payload
- Possible Responses
- Possible errors
For each route, we need to define:
- HTTP Method
- Path
- Description
- Parameters
- Headers
- Request Payload (for POST / PUT)
- Responses
- Possible Errors
The options for HTTP API documentation are more broad than those for WebSocket. Assuming that the end deliverable is a static spec, we will likely have to get that in ReSpec (I assume). However, we may want to provide this documentation in another, more familiar style for consumption by developers.
A quick survey of some options:
- RAML (http://raml.org/)
- Swagger (http://swagger.io/)
These provide a standard documentation format that can be comprehended by all sorts of different tools and languages; however, both are focused on allowing developers to "try" the API right from their browser, which may or may not be useful for our application.
- API Blueprint (https://apiblueprint.org)
- DocBox (https://github.com/mapbox/docbox)
These are more documentation-focussed and provide greater flexibility for more prose documentation, but can still be rendered into more usable documentation formats. For example, DocBox uses readable markdown (https://github.com/mapbox/docbox/blob/master/content/example.md) and renders it into an interactive explorer-style documentation (https://circle-artifacts.com/gh/mapbox/docbox/38/artifacts/0/tmp/circle-artifacts.jMIoUkM/index.html#update-a-wobble).
- Markdown
- ReSpec (https://www.w3.org/respec/)