Written By: Edgar Ramirez

This article has been kindly reproduced by wizeline.com

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 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.

Written By: Kara Latz

This article has been kindly reproduced by instructionalsolutions.com

Are you looking to understand what technical writing is and how you can become more proficient?

Technical writing continues to be a highly coveted skill in the professional workplace. Demand is expected to grow at 10% from 2014 to 2024. This is faster than the average for all occupations.

In this article, we cover the exact definition of technical writing. We also show you an average day for a technical writer, how to improve your skills when writing complex documents, and why the field is quickly changing.

Traditional definition of technical writing

What is technical writing? The traditional definition of technical writing is:

Technical writing is the practice of documenting processes, such as software manuals or instructional materials. Traditionally, it was limited to user manuals of some sort.

Frankly, this definition has become outdated. Technology moves quickly, and lexicographers are often left playing catch up.

New definition of technical writing

Today, technical writing encompasses all documentation of complex technical processes. It includes reports, executive summary statements, and briefs. Any time technical information is conveyed in writing at work, it is, by definition, technical writing.

This can include high-tech manufacturing, engineering, biotech, energy, aerospace, finance, IT, and global supply chain.

The format is no longer bound to lengthy user manuals. Technical information must be distilled and presented unambiguously. This can come in the form of technical reports, emails, policy, briefs, and press releases.

The bottom line is if you work in a technical field you are most likely performing technical writing.

How is technical writing different than business writing?

The new definition starts to sound a lot like the definition of business writing.

However, a business writer focuses on business plans, case studies, e-books, and sales/marketing collateral. They are experts in strategy and business management. 

In contrast, technical writers have a strong aptitude in the field of science, engineering, or IT. They are tasked with the compilation of technical documents such as instruction manuals and other instructional materials, guidebooks, technical product descriptions, and research reports.

What is the job of a technical writer?

The job of a technical writer will differ depending on the industry and company that they are employed with.

They often work on multidisciplinary teams functioning as the mediator between the more technical staff and less technical readers. They will work closely with these teams to develop a communications strategy.

Their responsibilities often extend beyond just writing. They must understand the entire project from high-level goals to the intricacies of implementation.

What is the job of a technical writer?

The job of a technical writer will differ depending on the industry and company that they are employed with. But the important task of a technical writer is taking the highly complicated and sometimes confusing subject matter, and putting it in a digestible format.

This is of particular importance in a variety of industries but specifically science or technology such as biotech, engineering, manufacturing, software, and healthcare. 

Technical writers often work on multidisciplinary teams functioning as the mediator between the more technical staff and less technical readers. They will work closely with these teams to develop a communications strategy.

Their responsibilities can extend beyond just writing. They must understand the entire project from high-level goals to the intricacies of implementation.

Educational experience for a technical writer can vary, but the majority of professionals hold a BA in English with an emphasis in writing, journalism, communications, curriculum development, IT, software/computer, or engineering. Some also possess an MA in technical writing. 

The bottom line is that whether accumulating related knowledge or expertise through formal education or hands-on job experiences, a good technical writer must be skilled in translating technical jargon into layman’s terms. Strong communication skills and technical writing skills are crucial. 

A day in the life of a technical writer

Many excellent writers are intrigued by the work environment of a professional technical writer. They find the quiet and tranquility of the atmosphere as a genuine job perk. Being alone with just a computer for researching and crafting documents through a technical writing process appeals to the introverted. Writers from all corners of the globe share their love for a job that can be more of a passion. 

When defining what technical writing is, it’s important to look at the persona of a technical writer and explore dominant character traits. Unsurprisingly, a professional in this field is marked as artistic and investigative. They are especially inquisitive. A fun fact is that Leonardo da Vinci is deemed the most famous technical writer of all time. Apparently, during the period of the Renaissance, he wrote ‘user manuals’ for his unique inventions.

As you further your understanding of technical writing and your technical knowledge, you may want to evaluate if it matches your personality type. It’s recommended to do a self-assessment and consider your personal strengths and talents when pursuing a new professional career.

Skills needed for technical writing

To be a successful technical writer, there is a core set of skills that you will want to master. Here are some of the most common skills needed to be successful: 

Research

Research is one of the first steps in technical writing. After you have an assignment, you will be responsible for collecting the data (numerical and non-numerical) and turning it into valuable information.

Research can come from a variety of places including:

• On-Site Data
• Online and Intranet Publications
• Interviews
• Libraries and Research Databases

After you have researched, you will need to synthesize and begin planning your document organization.

Audience perception

The technical information you research and gather has to be shaped for reader interest, understanding, and perception.

Technical writers often have to communicate highly technical information to a non-technical audience. Therefore, an early step in the most effective technical writing process is analyzing your audience carefully so you can match information to their needs.

Communication skills

Communication skills are imperative to be a successful technical writer. You will likely be working with multiple teams and individuals from differing roles.

Your ability to listen, record, and communicate will be crucial.

Technical skills

It is imperative that you understand the technical nature of the content you are writing about.

It is difficult to clearly convey a concept that you have not mastered. Many technical writers have academic or work experience in the topic they are writing about and many technical writers have job titles of engineer, geologist, seismologist, financial analyst, or business analyst. They are employed in technical positions and have to summarize information cross-functionally to other areas of the company.

Technical writing is slightly easier if you come from the technical side and are learning to write. It is sometimes more difficult if your background is in writing and you are trying to learn the technical content.

Writing

Excellent writing skills ensure your documents are easy to read and are free of errors. Writing encompasses many of the other skills on this list.

It is important that you have the correct tone, style, and format for your document.

Often these rules are outlined by the employing organization in a style guide.

Document design

It is important that the graphics aid the reader in comprehending the information. Graphs, tables, and charts are commonplace in technical reports.

You will also need to be proficient in formatting documents. The formatting should be professional and aid the reader in navigating the document. Headings should be easy to skim, and the content should be organized logically.

A poorly designed document will make it more difficult for the reader to understand the content. Document design is a key aspect of technical writing.

Fluency with digital tools

Today, writers must use multiple tools during the technical writing process. This often goes beyond basic text editors. Technical writers are expected to be able to create graphics and annotate images and screen captures and extract data from Excel and convey that data in charts and tables.

User research and testing

Some forms of technical writing may require user research and testing. An example application where detailed research and testing would be appropriate is a written guide instructing engineers how to fix a faulty mechanism on a deep ocean oil rig.

It is important that the documentation is easy to follow, especially if the application is crucial to a major function. To accurately write the guide, the writer may first observe how engineers solve the problem. They may use recording devices or just notes to write down the research. This type of research is closely related to testing.

Testing is necessary to ensure your document functions as intended.

After the writer has completed a draft of the document, they may give it to a test group to read. They can then observe the end users following the instructions in real-time.

They may follow up with a focus group or survey to get feedback on the usefulness of the document. They will use these real-world insights as they revise the document.

Even in less complex or critical applications, it is always a good idea to have a third party read over the text. This helps combat the curse of knowledge. The curse of knowledge is a cognitive bias that an individual has when trying to explain something they already understand. As an expert, it is hard to put yourself in the shoes of a learner who is less experienced.

This is why having a second set of eyes look at the document can help alert you to areas that need to be improved.

This article has been kindly reproduced by techguide.com.au

Technical writers simplify complex, technical information into layman’s terms. But while a thorough understanding of grammar and good writing skills are essential, technical writers require more than that. 

In this article, we will discuss the key skills you require to improve your writing and become an excellent technical writer. 

Key Skills You Should Have as a Technical Writer

Technical Knowledge

Technical knowledge is a prerequisite for being a good writer in the said niche. During your research, you come across jargon that you must be able to understand or at least look up and comprehend the meaning of. Without a passion for the technical niche, you won’t be able to convey these complex terms in simple words. 

For example, a troubleshooting guide about Windows requires specialized knowledge about the software. Similarly, an article about heart surgery needs a thorough understanding of medical terms. Such knowledge can only be developed by spending considerable time studying the subject. 

Most technical writers achieve this expertise by niching down. Whether engineering or medicine, writing multiple articles only in a particular niche eventually gives writers authority on the subject. So, while you figure out your niche, you can ask a professional paper writing service to write my essay so that you don’t miss any assignment deadline. 

Research Skills

Usually, technical writers aren’t subject matter experts in a given field. However, they develop excellent research skills to write a well-informed article. Good research forms your writing base, especially when the topic is unfamiliar. 

Before you begin your research, formulate a framework to decide what information to include. Then, identify the sources of information and organize the data according to the outline. 

Though a Google search gives access to lots of information, that shouldn’t be the only component of your research. Technical writing requires accurate information from reliable sources, something conventional search engines might miss. 

Instead, browse reports and research papers through Google Scholar, ResearchGate, and other educational databases. And if you have access, it is good to refer to books, whether hard or e-copies. Sometimes, books contain information that isn’t freely available on the internet, especially about technical topics. 

However, ensure that all the data is up to date. Topics such as technology and medicine evolve at a fast pace, which means even a year-old article may not be credible on a given date. 

Audience Analysis

Analyzing your audience is crucial for the proper presentation of technical information. What age group or professional positions do they belong to? Do they understand technical terms? Understanding the knowledge level of your readers is key to determining the usage of language and words in your writing.

A reader already acquainted with the topic may not need in-depth definitions of all the technical terms. However, a new reader may be confused if you use technical jargon. 

Similarly, a product report requires the use of specific terms, while beginner’s guides are best written in layman’s terms. When writing technical articles, you need to ensure that the information is conveyed to the audience at their level of understanding. 

Before starting a technical piece, consider your audience’s needs and expectations from the article. For example, do they seek information or solutions? Are they beginners or experts in the field? Do they have any specialized knowledge on the subject? 

Answering such questions gives you a brief idea about your target audience and ensures that the article meets their expectations.

Technical Writing Skills

As a technical writer, you need to understand various writing formats, such as user manuals, product reports, etc. While some gigs allow the writers to be creative, most technical projects follow a strict writing format. 

For example, a user manual has instructions on how to install or use a product. Similarly, case studies contain information on how a particular problem was solved through the company’s solutions. Each of these has specific writing formats that a technical writer needs to know. 

However, all technical writing formats depend on the clarity of the text. A user manual with too many complex terms fails to meet its purpose as the end-user may not understand it. A good technical writer maintains a balance between jargon and simple language while sticking to the boundaries of the writing format. 

Usage of Digital Tools

Nowadays, technical writing isn’t only about writing but also about the presentation. And this includes the design and visual representation of the project. As a result, technical writers are expected to be well-versed in using digital tools for writing, designing, and editing. 

While all writers use writing tools such as MS Word and Google Docs, you can polish your writing through editing tools like Grammarly and Hemmingway. These tools correct grammar mistakes and increase the readability of your article. 

In addition, you also need a basic understanding of Adobe Photoshop and Canva. These tools are helpful for visual designing, which you may require for some of your projects. For example, you can better demonstrate the working of a product by a graphic than by words. In such cases, visual designing skills come in handy. 

Ace the Technical Writing

Practice and persistence make a great writer. But what makes them even better is honing their skills. While technical writing is ever-evolving, the above skills are a staple for all writers in this field. With constant practice and a little patience, you can acquire the above skills and master the art of technical writing.