4 ms·
While "Time to 200" is an important metric, it's also important to have complete enough documentation for people to effectively use the API. There shouldn't be
by justin_oaks 5y ago
While "Time to 200" is an important metric, it's also important to have complete enough documentation for people to effectively use the API. There shouldn't be wholly undocumented corner cases.
For example, I was using the Docker Engine API and I was trying to use the container GET archive call. The documentation says to use a file path, but it doesn't indicate the behavioral difference between using a file path ending in "/" and one ending in "/."
I had to look at the "docker cp" documentation to figure that out.
If your documentation makes it difficult to complete a project because it only covers happy paths or frequent uses, then your users are going to have a rough time.
Both the "Time to 200" and "Time to real project usage" indicate how important usability testing and documentation is.
- dylan604 5y ago>only covers happy paths or frequent uses, Maybe, but there's no way a dev can possibly think of every single crazy thing an end user will try to do. There's a reason things are referred to as edge cases. You design a system to to work a specific way, and then document the workflow to make it work. Anything outside the documented procedure is eperimental. Sure, a dev can build as many bozo tests into the thing that they can think of, but users will always come up with something different.
- justin_oaks 5y agoValid point. Perhaps use of "corner cases" didn't help my point. I mean that there shouldn't be valid, intended functionality that remains undocumented. Another example is an API I use that has a property that has no documentation other than the property's presence. I just roll my eyes at that.
- gowld 5y agoIf your API has unpredictable corner cases, your data model or API is wrong