Category Archives: Uncategorized

Fabrizio Ferri-Benedetti recently published this post about failing as a technical writer. It’s raw and honest and made me think hard about how I operate as a writer of software (and now APIs). Of all the points raised in his post, the one that hit me square between the eyeballs was the section entitled WhenContinue reading “A reminder to talk more about tech writing”

Long-time readers will know that opportunities for me to document APIs have come only from open-source and freelancing work. And those have been few and far between. Excited to report that I’m helping the dev team at my workplace to document our new customer web API which is being built from the ground up! SoContinue reading “Helping to document an API in my day job”

Since July last year, I’ve had the privilege to work with a number of organisations both here and overseas as a freelancer, outside of my day job. I have freelanced on and off over the years while still holding down a full-time job, but the last six or so months have seen me step thingsContinue reading “Freelancing update”

Feeling pretty special this week. My interview with TechCommNZ got published and it’s gotten a lot of nice, positive feedback. One of the key messages I’m getting is that despite not fully understanding everything I discuss, people get a sense of what I do professionally, and appreciate the scope and reach of the projects I’mContinue reading “Great week”

Last year, I was invited by Weber State University to participate in some research about technical writers operating in New Zealand and Australia. I also helped to advertise the research through TechCommNZ and LinkedIn to increase the pool of participants. Fast forward a year or so and the research is published. It was an honourContinue reading “Research about tech writers”

I just submitted five PRs to the Redocly project using GitHub Desktop. Got my forks, clones, branches, commits and PRs sorted out. Five PRs successfully submitted and awaiting review! Couldn’t have got this far without the help of Swapnil and Ivana (Redocly) and Ralf (docToolchain) for their grace, patience and willingness to teach me theseContinue reading “*Wipes sweat off brow…”

I’m at the end of week two of my Redocly contract and the team has made me feel so welcome. Swapnil spent an hour this week teaching me how to use GitHub Desktop so I can start updating docs files locally and submitting pull requests. His instructions were very clear (he is a fellow techContinue reading “Getting the gist of GitHub”

Yesterday I attended my second online meet-up of the apidays Women in APIs group. There were three discussion areas that participants moved between: APIs as a product, inclusivity in APIs (and tech in general) and API development. All three discussions were interesting and many perspectives were shared. Of particular interest to me was Shanae’s groupContinue reading “Lots happening”

So I decided to do some more work on the docToolchain open source project over my break. I changed three files and committed those changes against my fork then sent Ralf a message in our slack channel proudly telling him about my work. I knew he would get a notification of the changes but thoughtContinue reading “Google “pull request anxiety””

For me, professionally, 2021 was actually a great year. I know this statement comes from a place of privilege. Many people in my community, my country, and around the world have faced challenges brought about by the pandemic. I’ve had a stable job and income throughout, the freedom to work from home, and no smallContinue reading “2021 was a great year”

Back in October, I put a call out on Linkedin for an opportunity to gain more experience in the API/dev docs space. Despite lots of views and a few comments, nothing materialised. “Give a rookie a chance!” was the subtext. And today, someone has given this rookie a chance. Enter Swapnil Ogale from Redocly. SwapnilContinue reading “Reaching out, giving back”

And not in the way you think. Up until now, I haven’t mentioned my API journey to my current employer (my day job) where I am the sole tech writer. I write end-user online help and design UX labelling/messaging, and haven’t written any dev or ‘technical’ docs of any kind in the whole time I’veContinue reading “I came out today”

Last night, I had the privilege of attending the quarterly online meet up of the apidays Women in APIs group. About a dozen women who work with, in and around APIs attended (there were two sessions available, depending on your time zone). Attendees came from all over the world, from Finland to Spain, from FranceContinue reading “apidays Women in APIs Online Meet Up”

Since 2018, Pronovix has hosted the annual DevPortal Awards which recognise excellence in documentation portals for developer and API docs. I am all heart eyes over Mercedes-Benz’s portal, so they’ll get my vote this year. The ease of use, friendly language and utter beauty of this portal is an inspiration. This is what I willContinue reading “DevPortal Awards 2021”

Just as I was wrapping up the Nextory project, I got an email from Tara, the Head of Customer Success at Portainer. They need a technical editor to run their eye across help content which is being migrated from their old docs platform to GitBook. After we agreed on my availability and fit for theContinue reading “A new gig”

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. IContinue reading “Project handover”

I’ve been trying for some time to document Nextory’s non-HTTP error codes into the definition. Each time I’ve tried, the schema was rejected due to the 4 and 5-digit codes (standard server codes being 3 digits). Well today, I worked it out! I’ve been trying to work more in the YAML than in Stoplight’s UIContinue reading “Breakthrough”

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.Continue reading “Empowerment”

So far, this blog has been a bit sporadic. I realise that I haven’t spent any time explaining my learning journey up to this point. I’ve been a follower of Tom Johnson’s I’d Rather Be Writing blog for several years. Some time in 2019 I started thinking more about his specialty (API docs). Indeed, heContinue reading “My learning journey (so far)”

10 out 0f 60 endpoints documented so far. 2120 lines of YAML in the API definition file. About 30 hours spent. Building an API definition in YAML is slow-going. I am using Stoplight to build it, and toggling between the code and the UI. Every few days I send a bunch of questions to DanielContinue reading “The slow build”