Tech writing stories from the trenches - by Swapnil Ogale

Introduction

It was late 1990s and while I was finishing my undergraduate studies, I was also taking extra classes on how to code, how to use programming logic, and how to create software applications. At one of these sessions, someone mentioned possible career paths - programming, project management, software testing, and technical writing. That piqued my interest. I’ve always been fond of writing and marrying my passion of learning new technology with writing seemed like a pretty good union. I decided I wanted to be a tech writer. 

A few years later, on a different continent, an opportunity presented where I could actually study to be a professional technical writer, courtesy the Graduate Diploma of Technical Communications at Swinburne University. This is where I met some of the coolest lecturers who taught me a lot about technical documentation. 

In my last semester, I got my first role as a Technical Writer and I was thrilled! After a few years learning the tricks of the trade and picking up some invaluable experience, I decided to switch to contracting. I’ve been contracting as a Technical Writer since 2010. 10 years of sweat, toil, blood and tears (lots of this!). 

Over the years, I’ve had the opportunity to work on a number of projects where I have been their first technical writer, or someone coming in to help out with documentation and setting up expectations around technical content. It hasn’t always been smooth sailing. There have been frustrations and anguish at proceedings. 

The following are some real stories from the documentation trenches.

Tools and tech

At a project kickoff meeting, working on a technical project, the developers and API integration teams were getting excited, fearlessly throwing around terms like containers, microservices, and messaging protocols. The Scrum Master was daydreaming about Kanban boards and Agile methodologies, and the testers were already discussing automation when the tech writer walked into the room and asked them “How would you like me to deliver this technical content to our end users?”. 

The verdict was swift. “Word documents or PDF, so that it is also easy for us to review any changes”. 

As a technical writer, nothing throws the spanner in the works than hearing how the technical team treats documentation and the publishing workflow.

Most technical writers, if not all, are highly competent and technically equipped to match the toolset of the developers and the product team, but often get relegated to archaic tools and processes. 

The key is to establish your credentials early in the project, which often leads to a lot of knowledge sharing and collaboration. I’ve used a mix of things to establish creds early in the project:

• Being proactive by asking the hard (and often tricky) questions especially highlighting the user experience.

• Diving deep into the product requirements and identifying 1-2 problems that can easily be solved by good technical content. When you can propose solutions even before the product design is up, it makes for a good case for including you in the process.

Unrealistic expectations

I was working through a tricky piece of the technical docs, when the Product Manager (PM) came over to my desk. 

Out of breath, he asked me “Can you create a draft of the user guide by tomorrow?”

Me: Sorry, I thought you said tomorrow.

PM: Yes, I did say tomorrow. Can you create one?

Me: I am sure I could rustle up something if the developers give me a test-ready version of the user interface. As far as I am aware, the UI is not even ready. Can I at least get access to whatever the developers have worked on so far?

PM: Can’t you just set up an outline of the user guide, along with headings and empty paragraphs using the functional requirements?

Me: I could do this, but what purpose will it serve? Will this be distributed?

PM: Oh, yes, I’d like to send it out to our end users by the end of tomorrow.

Ever been in this situation before? It is true technical writers are content magicians, but even this is beyond the comprehension of the most powerful wizards. 

The trouble with a lot of projects, especially new ones, is that there is no expectation setting, no education to the teams on how technical writers work to produce deliverables, or any understanding of the content development and publishing process. I’ve been astounded at the number of times technical content has not been factored in at all in the whole product delivery.

This is a fight worth fighting to be honest. 

• Educate the team at every single opportunity, to make it a habit for teams to be in sync with the content development workflow. How about creating a documentation plan that captures all this crucial information and something that can be presented as part of a sprint planning? 

• Advocate for your right to be included in the project right from the planning stage. For one project, I was doodling some concepts in my notebook during a meeting for my own understanding. The PM saw this and this diagram actually ended up as part of the final documentation because the PM thought “it exactly depicted how the product components fitted in with each other”.

We didn’t know . . .

A few years back, I interviewed at a software company that had been around for a few years. Not surprisingly, I would be their first Technical Writer. 

During the interviews, they admitted how ad hoc their content processes were, and asked me a whole lot of questions around specific scenarios of the user content experience. I explained, and demonstrated where applicable, the various methods we could employ to produce content to meet user needs. 

Some of these methods included performing a content audit to identify gaps, usability testing, documentation workflows, automating parts of the content (Release Notes), use of diagrams, working with developers on identifying content related bugs, and helping the QA team with testing the product interface. 

This is when the interviewers confessed “We didn’t know Technical Writers really did or can do all of this”. 

I am constantly amazed to see a whole lot of organisations in Australia that have never worked with a Technical Writer before, and are often found lacking in understanding what skills Technical Writers bring to the product development process. Content professionals still need to do a lot to promote their skills and value to a larger audience. 

One of the ways this can be done is to put your hand up for speaking at various meetup events. Meetup organisers are often looking for speakers and don’t mind someone presenting a unique perspective on a topic. This is your moment to shine the torch on the technical content profession, nice and bright! 

We didn’t realize . . .

I was in the thick of things, rushing against timelines, documenting no less than four deliverables when I was given access to an API collection by a developer. I quickly jumped onto Postman, executed the API requests to validate the responses and variables, before making appropriate updates to the API guide. While I was doing that, I found a couple of typos in the code and got the developers to fix it right away.

When asked by the Technical Business Analyst and the Project Manager how I managed to get the documentation done without setting up meetings with the developers or the testers, I told them. 

Their response “We didn’t realize you had access to these tools, or that you could even read the API content and test it out”. This essentially plays out like a scene from a movie where the lead character gets to experience the same moment over and over again. 

I know a whole lot of technical writers who are equally good with coding, designing, project management, product management, testing and system analysis in addition to their core skill - technical writing. Organizations often fail to realize that such a person essentially exists. 

It comes back to the same thing - education and an early understanding and expectation setting of the different skills Technical Writers can bring to a product. 

Use your project kick-offs to do a lightning talk as an ice-breaker. Summarize your previous non-writing achievements and back up your claims with numbers.

You don’t need a technical writer. Until you need one. 

That’s it. That’s the message. 

Over the last 10 years, I’ve been through a lot of interviews. Some good, some not quite so. 

I’ve seen organizations a bit clueless about documentation. Sometimes, they are not even sure they need a technical writer. 

Then, there comes a time when an organization finally feels the pain of having multiple people trying to own the documentation and support material resulting in noise and not enough value. In a couple of interviews over the last two years, startup founders have confessed  “we are a bunch of people trying to do our best with helping our customers solve their issues for themselves, so that we can get on with delivering a superior product. Our technical documentation barely exists and we have users crying out for this all the time. It is time we got in a specialist to help us out with solving this bottleneck.”

That is when they truly need a technical writer.

Final remarks

Technical writing is fun, wholesome and entirely satisfying, but it comes with an ever hanging sword of expectations - education and almost a bit of self promotion. While I am not a natural speaker and still get cold feet before a talk, I’ve pushed myself to stand in front of a room of unknown people and talk about how I can add value.

Almost every project I have been a part of, writing has probably been the least of my worries. The difficult part has been bringing everyone on the same content journey.