Project handover

Very early on Friday 13 August, I had a video call with my Nextory contact to formally hand over the project. It was our first face-to-face meeting, as we’ve been communicating over email since the project began in April.

Nextory is very happy with my work and gave me a glowing review on Upwork. I returned the compliment, mentioning again how lucky I feel to have had the opportunity. I am still glowing from it all. I’m so proud of myself for having taking the leap, reached out and connected with such an interesting company.

I learned a lot from the experience. Like other documentation, documenting an API is time-consuming, highly detailed and involves close collaboration between SMEs and writer. But because you’re working with the OpenAPI Spec, the rules are strict. Everything must validate, and you cannot have a line of code out of place.

Docs-as-code is also a very different space in which to write than other formats. I’m used to producing content for web, mobile and print. It’s all very WYSIWYG in those universes. But when you’re down and dirty in Markdown, YAML or JSON, it takes a little while to let go of previous ways of working. You’re producing functional and highly technical information that must be portable and readable by both machines and humans.

Documenting an API retrospectively works fine, but I can now very clearly see the value of a design-first approach to building an API. Using the OpenAPI Spec to design and document an API before a line of code is written is really where it’s at. Maybe the next project I take on will give me the chance to use this method and come at an API from the beginning rather than at the end.

I also learned that developer docs are where I want to spend my time and where I will focus my career (in consultation with my employer of course). I will continue building on this experience with hopefully one more practice project, then I’ll put my name out there and actually charge money for the service.

I’ll end by saying that I feel very at home in the API space!