My First Month as a Technical Writer

Adapt and Pivot.

These phrases have been thrown around for the past one and a half years as companies and people struggled to find their footing in the midst of a pandemic. Back in March 2020, I had to pivot from a Digital Content Specialist to a Digital Marketing Associate. Fast forward to March 2021, I’ve had to pivot from a Digital Marketing Associate to a Technical writer.

Although the path that led me here could have been shorter, I don’t regret it.

Creating a Writing System Has Been Challenging

While marketing technology only needs Google Docs, Microsoft word and a personal formatting template, technical writing requires you to learn the inner workings of Gitlab, install Gitbash and learn how to branch from the developer branch, create your own branch, make your edits on your own branch then push those edits to the developer branch.

Sounds easy right?

It isn’t. It’s easy if you’re coming from an engineering background, but it isn’t if you’re coming from a marketing and writing background.

My main hurdles were:

  • Creating my working branch. Somehow I ended up creating this wrong so I couldn’t push my files.
  • Pushing my files to Gitlab. I solved this by moving from Gitbash to the Command Prompt to see the file that was giving me errors on Gitbash. Eventually, I had to clone the repository and create a new folder for it.

All this wasn’t without help.

Tools and Tooling

The tools recommended to me were Apiary, Postman, Swagger and Soap UI. I’m yet to try out or look into Soap UI. I started with Swagger, hit a roadblock and went through Apiary. Although I’m not using Apiary, I love how their company blog explains technical writing to a new person and their examples.

I spent most of my days going through their blog posts and trying out their examples. This helped me learn Markdown formatting, resources, actions, paths, routes and workflows.

I eventually went with Postman as a start, and I’m currently learning how to use the tool for API documentation.

On using Postman as a Documenting Tool

While Apiary has a lot of great resources for anyone green in technical writing, it wasn’t straightforward as Postman. With Postman, I could run requests, save them and their responses, write descriptions for the requests and have Postman edit for me in Markdown without stressing about the formatting.

It’s a good tool to build confidence in technical writing before learning Apiary, Swagger or SoapUI.

Here are concepts that might sound obvious but are not while using Postman:

  • To run requests, you might need to get authorized either through a token, API key or other authorization forms.
  • To make your work easy, create an environment with variables that are repetitive such as URLs or authorization headers.
  • Fork the Postman API to have a feeling of Technical documentation, how to format documentation and what to include in your documentation. Previously, I was explaining the process but I found that describing what each endpoint achieves was much easier.

I’m still going through Postman and learning all that it offers. I’m currently looking at creating Mock servers and what that entails from a technical writer’s standpoint.

My first month has involved a lot of learning, testing and reading which is a welcome respite from the plateau that I was in the marketing genre. I still do marketing related work when it’s worth my while or gives me joy, but I’m looking forward to learning all I can in this niche.

This article first appeared on Medium.

(Visited 17 times, 1 visits today)

Leave A Comment

Your email address will not be published. Required fields are marked *