Empowerment

Documenting the Nextory API using the OpenAPI Spec has revealed inconsistencies in the naming conventions of query parameters and response fields. These range from the minor (casing) to the more serious (different descriptions of the same thing, parameters required or optional at different API versions).

The purpose of the OpenAPI Spec is to define APIs. This will ideally happen before the API is actually coded. That way, you get to decide conventions, schemas and all of the other attributes that make an API. Because the Nextory API is already developed, part of my job is to find the inconsistencies and highlight them so the devs can go back and examine the code and make the relevant changes. Although retrospectively documenting an API is not the most efficient method, as a tech writer, it is pretty empowering to be in a place where I can provide constructive feedback that will help to improve the product.

Writing end-user help is not as empowering. First, users are reluctant to read it. Second, it’s thankless. Users seldom thank you for writing great help, they just expect it. And third, you have to document the product ‘warts and all’ including poor design and questionable functionality.

The company I work for has finally started involving me in product design. This can include anything from feature design to messaging to field labelling. Getting in front of the actual development, and having the chance to shape the software, is much more fulfilling than documenting the end result.

Although the Nextory API docs have been an amazing learning experience, I am hopeful that the next project will see me working alongside a team that is planning an API, so I have a part in shaping it.