API Documentation Revision Approach: Phase 1

[RanyeM]

This is a draft ticket for consideration and revision.

What problems are we trying to solve?

The API documentation was written piecemeal. Based on the experience of answering user questions in the HD and in the api-dev mailing list, the documentation could be much better structured to support users working with the API.

We would like our API documentation to help our users understand what is possible with the API, and how to do it.

What can we do today?

We can begin by drafting documentation structure/plan content, noting where reuse is possible, updates are needed, and new content needs to be generated.

1. What do we want to keep or remove from the current documentation?
2. What options are available to replace or enhance the current user experience?
3. What support is needed from the team?
4. What can be done and not done with the API?
5. Who is the audience?
6. How to document errors: What approach should be taken to documenting API error messages and exceptions?
7. How to keep it up to date: As the API evolves, should the documentation be updated to reflect those changes?

### Tasks
- [x] Meet w/ Dan and Matthew to discuss next steps
- [x] Sort feedback by topic/area of focus with updated site structure in mind (i.e. where will we combine sections? Which ones will we get rid of? Do we need any new sections?)
- [x] Meet w/ Dan about versioning history
- [x] Meet w/ Sudha about Historical Data page
- [x] identify any redundancies, suggest what can be removed or combined
- [x] Receive feedback before proceeding to next steps

[RanyeM]

https://docs.google.com/document/d/1ul0WvWLFB37wBvgqf8LI3ekMftGrlrjQMeWVm19Dy_Q/edit - current document plan, open to revision