search

GSA-TTS / FAC

GSA's Federal Audit Clearinghouse
Other
19 stars 5 forks source link

Research API documentation revision #3909

Open jadudm opened 4 months ago

jadudm commented 4 months ago

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 doing some desk research and planning.

  1. What are examples of excellent API documentation? What are some best practices? (These are offered as starting points, not as the be-all-end-all.)
  2. What kinds of questions have been asked by users in the past?
  3. What do we think we can keep from our existing documentation? What needs to be changed? Added? Thrown away?
  4. How should the API documentation be structured, given best practices in the space?
  5. What do we need to learn in order to develop this content? What support might be needed from the rest of the team?
### Research and planning
- [x] Capture/highlight/document representative/key questions asked by users previously
- [x] Work through the existing docs locally to ID themes, issues, ideas.
- [x] Identify/document excellent examples and best practices
- [ ] https://github.com/GSA-TTS/FAC/issues/4104
- [x] Identify spaces for learning in this work, and what support/resources are needed to achieve that learning

Feel free to edit/extend the research/planning checklist as needed.

jadudm commented 4 months ago

Many thanks, @Liamhhhhh ; we'll definitely look at what tooling we can leverage (we generally need to use libre/open source tools) to generate endpoint documentation.