Good documentation - the YouTube Data API
Recently, I wanted to get some information about a few YouTube channels and ended up exploring the YouTube Data API. I expected the learning curve, but it was made much easier by the quality of documentation.
The primary Reference page provided a brief overview of the API.
Later down the page, there was a list of all the different resources with an overview for each.
The documentation was filled with hyperlinks - references to detailed pages with more information or details within the same page.
Unrelated to documentation - All the API method reference pages had a side panel to actually invoke that API and check the response.
I was actually trying to invoke this API from Google Sheets. There was a page to get started to use the API in Google Apps Script, with additional code samples also available.
Recommended by LinkedIn
In summary, a lot of thought seems to have gone into how the documentation was structured, keeping novice users and experienced developers in mind. I now see that the API documentation has been maintained for around a decade. The writing is also very clean, without too much jargon.
A lot of questions on how this is all done.
If anyone knows about this process better (or any similar documentation efforts), let me know. Would like to understand and apply it where relevant.
In a lot of projects, documentation is usually given the least priority which increases reliance on the core IT teams to understand how a system actually works. Seeing good technical documentation that is easy to navigate and understand has made me reflect on its importance.
P.S.: Even after all this information, it took quite a while with a few missteps to get the API finally working on my end. That is more on my rusty programming (it's been a while). But hey, the end result is great and that’s good enough for now.
It varies based on different projects. I have seen product managers involved early during the design phase to create the OpenAPI spec(swagger) which has all these information. And the same will be consumed and implemented by developers as REST implementation. Most of those information will be used/consumed by professional services team to create customers exposed document which will have a bit of how-to and intro. There are a few projects where the developers are responsible to create and maintain the OpenAPI spec together with the documentation that is needed. From review perspective, every PR goes to GIT will be reviewed and well maintained. I have seen some CI implementations which will fall if there is a Controller code change, but the OpenAPI spec is not current. Personally, I feel having these documentation done early during the contract creation phase is a better approach which serves everyone involved in SDLC and the customers.
In most of the cases the technical documentation will be prepared by the developer himself or the technical details will be provided to content writer or product owner