If you had asked me a couple of years ago what technical writing is, my mind would have been blank. Maybe I would have tried to come up with something just to avoid embarrassment.

I even applied for a technical writing position in 2018, thinking that my experience in journalism was enough. I was wrong… but I was also correct.

A journalist has almost half of the way covered in becoming a technical writer. This article will explain the similarities and differences between both fields and how to combine them to find your way in the world of technology — all based on my experience as a technical writer at Wizeline.

For those who are neither journalists nor official technical writers, I hope this article provides you with a clearer perspective of technical writing and prompts you to try it as a professional career.

Similarities

First, I am going to highlight the similarities between journalism and technical writing. Here we go.

Interviews

In technical writing, believe it or not, you still have to interview people. They are what we call Subject Matter Experts (SMEs). They own relevant information for the projects we are involved in and for our technical documentation. 

Similar to a journalist digging into a politician’s mind, technical writers participate or conduct interviews with SMEs to understand things such as the project scope, the client’s needs, or the solution to develop.

There is nothing more terrifying than not knowing what a team is supposed to do on a project. Technical writers can help overcome this uncertainty by asking the right questions and putting all the answers in a document shared with everyone involved.

Research and Notes

The first steps of the technical writing process are research, preparation, and organization. They constitute the foundation of any document and take most of the time before even writing a word.

Technical writers collect all the relevant information for a project, such as basic concepts, technology stack, coding conventions, repository strategy, and even a list of keywords or terms for a glossary. We also take notes that can serve as a future reference, for example, about the decisions and agreements reached during meetings or workshops.

On the other hand, the core of investigative journalists is research. To reveal the truth about a topic, they rely more on facts and figures than personal or political statements. Numbers speak louder than words, they say.

Without information, it is almost impossible to start writing in both cases.

Reviews

Journalists and technical writers share the same step before publishing their work: reviews.

Reviews help detect errors or blind spots in documentation by removing writers’ bias in their work. A rule of thumb is to perform a self-review always, but peer reviews are highly recommended and encouraged.

Technical writers can ask for a peer review from other colleagues or teammates, such as developers. Journalists have their editors.

Style Guides

Journals and technology companies with structured writing teams commonly implement and follow a style guide. 

Style guides consist of standards, guidelines, and conventions for writing and designing documentation. Their purpose is to ease collaboration, reduce time in creating error-free documents, enhance accuracy and consistency, and develop a distinctive voice and tone, among other benefits.

An essential component of the style guide is the objective writing approach. Both technical writers and journalists are encouraged to write without adjectives, stick to the facts, and be concise and clear. So, marketing lingo is off-limits, as well as using synonyms to avoid repeating words.

Multidisciplinary Teams

Producing a journal or developing an application is not a one-person job. Multiple disciplines or roles are involved in the process. For example:

• Producing a journal
  • Reporters
  • Photographers
  • Videographers
  • Editors
  • Designers
• Developing an app
  • Developers
  • DevOps
  • QA
  • UX/UI Designers
  • Technical writers

And I only mentioned the directly involved disciplines in a journal page and a standard software development project. The list gets enormous if you include non-directly involved roles.

In both cases, collaboration is vital for success. Therefore, the more you are used to working with other disciplines, the better.

Ceremonies and Processes

When planning projects and tasks, journalists and technical writers have similar ceremonies and processes.

Considering software development methodologies, such as agile, scrum, and waterfall, the following table shows similarities in terms of ceremonies:

Terms such as sprint and product backlog can be translated into the editorial world. 

A sprint can be the daily work for the next day’s newspaper edition or the weekly tasks to prepare the weekend editions. A product backlog can be the list of articles and stories with different statuses and characteristics, such as the following:

• Exclusive
• Dependent on a public event
• Written or not
• Accompanied by photography or not
• Reviewed by an editor or not
• Ready and packed for publishing

Also, the product owner’s role in software development projects is similar to the editor-in-chief, editorial director, or whoever is in charge of defining what will be published.

Differences

Now comes the tricky part. 

Journalists know how to obtain, write, and structure information. They are used to working in multidisciplinary teams and following specific processes to get their articles published. However, journalists usually lack technical knowledge and skills, and this is where technical writers prove their worth.

Specialization

The main difference between journalists and technical writers is precisely the technical specialization.

You don’t have to be a developer to become a technical writer in software development projects, but you must have at least basic knowledge of topics, such as the following:

• Software and hardware
• Networks
• Cloud infrastructure
• Databases
• UX and design
• Coding
• Version control
• APIs
• Automation
• DevOps
• QA

This specialization is what enables technical writers to collaborate and add value to software development projects. Through documentation, they build communication bridges by translating technical and abstract concepts into information suitable for a specific audience, for example, end-users.

The list of documents a technical writer can deliver is huge, and it depends on the type of industry, the project or product, and the client’s needs.

Methodology

As mentioned in the Ceremonies and Processes section, journalists have similarities with the management part of software development methodologies. 

But what if I tell you that you can apply the same iterations approach from agile methodology to documentation?

Technical writers can deliver documents in incremental pieces. It all depends on the development progress and the project needs. For example, they can write about features as soon as they are released to production or about the current state of the software architecture. If anything changes, they adjust the documents accordingly.

Concerning deadlines or milestones, technical writers can create different versions of a document to meet those dates and keep iterating until the development process is complete. Journalists cannot deliver incomplete articles.

Version Control

Now that we’re discussing versions in documentation, get your mind ready to be blown with version control.

Some old-school journalists still use traditional word processors to write, and they end up storing multiple files with different versions of an article. Some others know how to use web-based solutions to boost collaboration (the editing mode is a big plus) and track documentation changes. However, only a few have heard about version control tools such as Git, CVS, or SVN.

In software development, version control is vital because it enables developers to do the following:

• Keep track of changes and comments in the source code
• Prevent and identify mistakes
• Go back to the latest error-free version of the software
• Maintain the code
• Facilitate collaboration among multiple developers by enabling them to work on the same source code without overlapping

Technical writers are immersed in this workflow. Moreover, they can implement version control tools to identify how a text evolved from the first draft and perform in documentation the same actions a developer does with code. Pretty cool, right?

Tools and Delivery Formats

Journalists have limited tools and delivery formats, unlike the wide range of possibilities in technical writing.

Most newspapers still print a version on paper (this implies space limitations) and usually have websites and social media accounts to showcase and share their articles. Journalists even have blogs to share content. But that’s pretty much what they offer.

A word processor (whether a native or a third-party solution) is the minimum requirement for journalists in terms of tools.

On the other hand, technical writers use different tools to deliver documentation in multiple formats depending on the project or the product’s needs. Here’s just the tip of the iceberg:

• Use word processors to deliver shared documents or PDFs
• Publish information on websites by working on Markdown files or HTML documents
• Implement a docs-as-code approach where we use the same tools and development processes in the documentation as developers do. Among these tools, we can use the same version control systems of the source code

If you want to know more about the docs-as-code practice, you can read our recent blog on Implementing a Docs Like Code Solution at Wizeline.

Let’s Wrap It Up

My journalist experience has, indeed, helped me in becoming a technical writer. It was an excellent foundation. 

Nonetheless, my journey in this new field has only just begun. With technology moving as fast as it does, I see a lot of learning on the horizon. It’s exciting!  

Technical writing is a relatively new discipline; therefore, it remains unattended by universities as a career. So, if you are interested, start reading documentation about it, take certifications, or watch tutorials online.

Our team offers a Technical Writing Certification through Wizeline Academy at least twice a year. Stay tuned for the next edition. 

You can also take a look at the open roles on Wizeline’s Careers page. We will be glad to welcome you to our team.