sokaribosenibo
Fundamentals of Technical Writing

Fundamentals of Technical Writing

Sokaribo Senibo S.'s photo
Sokaribo Senibo S.
·

10 min read

Starting a career in technical writing can be a frustrating process due to the abundance of information and misconceptions about what technical writing is and how to get started. This article summarises in detail the fundamentals of what you should know and consider when getting started in technical writing.

Table of Contents

  • What is technical writing?
  • The role of the technical writer
  • Skills required in technical writing
  • The technical writer's toolbox
  • Design thinking and the writing process
  • Starting a career in technical writing
  • Summary

What is technical writing?

Technical writing is a unique sphere that unites communication and technology. It is the art of providing detail-oriented instructions to help users comprehend a specific skill, technology, or product. There are misconceptions that technical writing is just about writing. In reality, it is also about researching, understanding a technology, determining the audience, problem-solving, and more.

Technical writing is part of a bigger field called Technical communications, which encompasses a set of activities that people do to discover, shape, and transmit technical information. The major difference between technical communication and the other kinds of writing is that technical communication has a somewhat different focus on purpose and audience.

The role of the technical writer

In simple terms, the role of a technical writer is that of a translator, whose aim is to explain difficult subjects to a specific audience in clear, easy-to-understand text. In organizations, technical writers work with multidisciplinary teams to develop a communication strategy, acting as a mediator between the more technical staff and the less technical readers. A technical writer’s responsibility extends beyond just writing to understanding the entire project, from high-level goals to the intricacies of implementation. Depending on the industry and company, documents created by technical writers can be divided into the following broad categories;

  • UI Based Docs
  • Developer Docs
  • Deployment Docs

UI-based docs are documents that capture details of the software user interface. They specify how the end-user may navigate the UI of a product or software. They include product manuals, repair manuals, user guides, etc.

Developer Docs are documents that describe every aspect of how developers should interface with a given software or library. A subset of developer docs is API (Application Programming Interfaces) documentation.

Deployment documents, on the other hand, are documents that assist users in deploying and securing a product or software on another product or software. They include SDK (Software Development Kit) Documentation, which are helper documents or libraries that guide developers when they create apps for a specific product or platform.

In general, technical writers produce technical documents that show the user the layout of products or processes, explain what lies ahead, and define how to navigate each step to achieve the desired result.

Skills required in technical writing

Different documentation requires a different set of skills. However, there are fundamental skills required in technical writing.

  • Critical and Creative Thinking Capabilities

    The importance of creative and critical thinking cannot be overemphasized. Technical writers have to be able to think through a problem, break it down into manageable bits, and make reasoned and clear judgments. They have to be empathetic and have the ability to teach or describe terms in ways suitable for the intended audience.

  • Writing and Research Skills

    An effective technical writer has to be an investigative reporter as well as a journalist. As a result, it is critical for technical writers to understand and have a good grasp of English, be a good team player, be able to conduct research and gather data through interviews, and put the results and information into clear writing.

  • Testing and Troubleshooting Skills

    Part of a technical writer’s primary task is to be familiar with the product’s features. As a result, before producing documentation, a technical writer may be invited to participate in product testing, which assists in the creation of an easy-to-understand guidebook. They have to go through each feature of the product one by one. After that, build a list of features that work well and another list of ones that don’t. In other circumstances, features may function properly, but the product design itself may be unappealing.

Technological innovation is consistently moving forward; new features and products are continuously designed. Hence, technical writers have to be able to quickly adapt and work with diverse technology tools. Technical writers are lifelong learners.

The Technical Writer's Toolbox

There are several software and tools required in technical writing depending on the project and company. Fundamental technical tools for technical writers can be categorised into the following;

  • Text development tools
  • Help or web authoring tools
  • Style guides
  • Publishing tools

There are several available options for each of the above categories of tools.

Text development tools

These are word processing, document processing, and desktop publishing packages that support authoring. Several technical writers use a basic word processing program like Microsoft Word. Although Word is adequate for short business documents, it can be inadequate for technical writing as it is not designed for long, complex documents. Other options include;

  • FrameMaker
  • MarkDown
  • DocBook

  • AuthorIT, etc.

    For a structured authoring environment, Extensible MarkUp Language (XML) authoring tools may be adopted in place of document or desktop publishing tools. Examples of XML tools include XMetal, Arbortext Editor, In.Vision, and Oxygen.

Help or web authoring tools

To develop online help or web-based materials, there is a need for a help or HTML tool. For online help, tools such as RoboHelp and Flare can be used. To write HTML, Dreamweaver can be used. To create documents for more than one output (for example, print and HTML), a text development tool with conversion capabilities or compatible third-party conversion tools should be adopted. There are several third-party tools that can convert word processing files to other formats, including online help, HTML, HTML Help, JavaHelp, and XML. ePublisher and MIF2GO are examples of third-party conversion tools.

Style guides

A technical writer's style guide is a set of guidelines that technical writers must follow when writing technical documentation. They define the style that should be adopted in technical writing. These style guides enable documentation to be written in a clearer, consistent tone and style. These guidelines explain issues such as:

  • The word counts
  • Punctuation
  • Capitalization
  • Word choice and terminology
  • Highlighting
  • Acronym use
  • Use of charts and figures

The style guide adopted is usually dependent on the type of documentation project. Most companies and technical writers develop their own style guides and distribute them to all employees in either printed or online forms. Other companies and technical writers may follow the guidelines in an established reference such as:The Chicago Manual of Style, The Handbook of Technical Writing, Open SUSE_, etc.

The Chicago Manual of Style is a guide that focuses primarily on grammar and writing style. It provides guidance for punctuation, capitalization, abbreviations, hyphens, dashes, plurals, and possessiveness. Technical writers can adopt this style when writing software documentation or technical information for the web.

The Handbook of Technical Writing offers guidelines for writing in a variety of technical contexts. The style guide provides tips for professional communication, organization and style, document design, tables, graphics, math notation, punctuation usage, and how to write technical documentation for other geographic regions.

Open Suse is an open-source style guide for developers and designers who are creating software documentation. The technical writer's style guide is a one-page document that provides guidelines for grammar, formatting, punctuation, capitalization rules, hyphenation of compound words (receipts vs. receipts), etc. It also specifies the preferred fonts as Liberation Sans Narrow with Arial or Times New Roman as backup font choices. Moreover, the guide has a DocBook markup at the end to help you select the right XML element and make your document easy to translate from English.

There are several technical writing style guides available, but it is important to adhere to a technical writing style guide that defines the communication standards for the documentation to be created. Technical writing style guides are fundamental considerations for any technical writing project. They are the blueprint for writers to follow when creating technical documentation.

The Technical Writing Process

Technical writing goes beyond just sitting down and typing; it also includes various tasks such as visual design, editing, and project management. The following technical writing process can be adopted:

  • Understand the task
  • Define your audience
  • Set up a doc plan
  • Get Started
  • Review and publish

Starting smart and following a process encourages success in technical writing.

  • Understand the project

    Understanding the project sets you up for success and makes your writing time more effective. Take time to clearly understand the task at hand. Note all the requirements; document type, subject area/content, scope, and goal of the project. It is important to identify the needed deliverables.

  • Define your audience

    One of the major writing factors in technical writing is the audience. Every technical writing project is targeted towards a specific user. Hence, the user should always be at the forefront of the technical writer’s mind. Enough knowledge should be gathered about who will use the document and what the user will be looking for when they read the document.

    According to Janet Mizrahi,

    "Knowing the audience, your reader, is imperative for successful writing..." In essence, we have to psych out the reader to accomplish our writing goal. We cannot do that unless we analyze the reader accurately. "

  • Set up a doc plan

    After understanding the task and the user of the document, conceptualize your document. Technical information can be complex. It is important to create an outline or overall project plan with a list of tasks for each deliverable and a draft schedule. Tasks can include outlining, creating storyboards, writing, editing, designing visual content, reviewing, and so on. While setting out your document, it is important to research the project.

  • Get started

    It is time to get started. Start writing by following the doc plan, having the audience in mind and understanding the project. Create the content, create the visuals, consult the subject matter experts (SMEs), and discuss with the team.

  • Review and publish

    After writing, it is important to review the project to ensure it achieves the goal of the project, is tailored to a specific user, is consistent with the style guide, and aligns with the doc plan. After reviewing, you may publish or submit the project. There are several platforms to publish articles and projects, such as Dev.to, Hashnode, and GitHub.

Starting a career in technical writing

Technical writing, just like any profession, has various processes, rules, best practices, skills, and so on that need to be understood. There are several online learning platforms and certifications available to learn these processes and skills and kickstart a career in technical writing. Preferred options include;

After learning, the major aspect of starting a technical writing career is to practice and build a portfolio. A portfolio proves proficiency in technical writing and showcases technical writing skills to hiring managers and companies in search of technical writers.

To build a portfolio, follow the following process:

  • Choose a technology or topic of interest
  • Write a tutorial on the technology or topic of interest
  • Write a how-to guide
  • Write a reference document
  • Write an explainer document for the technology or topic of interest

Conclusion

By understanding what you are getting into, learning the fundamentals, practising intelligently, building a relevant portfolio, and developing a practice routine, it becomes easier to make progress quickly and consistently. There are several open-source projects available on GitHub to improve your technical writing skills. Open-source projects are projects that are free to use, study, modify and distribute. To learn more about open-source projects visit Ruth Ikegah's blog. Also, joining a technical writing community is important to stay updated with relevant information and improvements in the technical writing profession.

There are several technical writing communities available, such as:

Technical writers tend to spend a lot of time in front of a computer, so it is important to have an ergonomic workspace to prevent repetitive motion injuries like carpal tunnel syndrome and other problems such as eyestrain. Always consider the height and position of your chair and keyboard, your posture, and the lighting condition of the work environment.

As you progress in your journey as a technical writer, there are other things you need to learn and consider. This article is intended to serve as a foundation for technical writing.

Feel free to reach out to me for clarifications, questions, job opportunities, etc.

Technical writing Beginner Developerswritingnewbie