Technically James

The Hitchhiker's Guide To Technical Writing

The Hitchhiker's Guide To Technical Writing

A Technical Writing Guide For Noobs of All Kinds

James 'Alexander' Akande's photo
James 'Alexander' Akande
·

12 min read

Table of contents

This post was first shared (mostly) on Zaycodes as a part of the the Zaycodes WriteTech Bootcamp.

Technical writing - the process of transforming dense technical information into formats that are simple and easy-to-understand; has become essential in a world that is increasingly being built on technology with each day unfolds.

Technical writing is a very lucrative career path (if you're willing to put in the work!), and the more technology encroaches into our everyday lives, the more we need documentation that simplifies technical concepts and explains how to use a product, platform or service - the work of a technical writer.

In this beginner’s guide, I'll try my best to provide a pretty good introduction to technical writing; giving you all you need to get started - as a newbie.

What is Technical Writing?

Technical writing refers to a type of writing that involves communicating complex information on technical topic, products, tools, or concepts in a manner that is simple, clear, and easy to understand. Here things are written with the aim of directing, instructing, or explaining to the reader; and simplifying complex facts for anyone (within the intended target audience) who need it to carry out a task.

In the world of software development, technical writing serves as a much needed bridge; conveying technical details about programming languages, APIs, platforms, and software to both developers and end-users; helping them easily navigate and understand the same. Because of this, a technical writer focuses on creating simple, clear and concise and simple. A technical writer focuses on creating simple, clear, and concise documentation - either to explain a concept, or to instruct the reader on a process (whether it's a guide, tutorial, or API documentation). In this tech-driven world, technical writers are in high demand.

Who needs technical writing?

As a technical writer, your skills find application across a variety of industries besides software and the IT industry in general - even though that is the focus of this article.

Technical writing finds use in the following:

  • Engineering & Manufacturing - Instructions on assembling, operating, and maintaining products.

  • Science & Healthcare - Guides for technical equipment and complex medical topics.

  • Business & Finance - Internal documentation, user manuals for tech-based systems.

  • Government agencies

  • And of course, the IT and software industry; as many devices, software applications, as well as their underlying infrastructure, need documentation. For the purpose of this article, this is our focus.

As you can see, almost every industry needs and uses technical writing in some capacity. As long as a field has been ‘touched’ by technology, it needs technical writers.

Why Are Technical Writers Important?

In a world where technology is constantly evolving, new products and tools are constantly being built, and people need to know how to use them.

  • Technical writing helps a software developer to share their technical knowledge/experiences with other software developers in software engineering.

  • Clear documentation helps users understand your product quickly and efficiently, reducing frustration and increasing satisfaction.

  • New users quickly become proficient with your product if they have access to well-organized, easy-to-follow guides, integration, and docs.

  • Technical Writing is essential for training new hires efficiently.

Types of Technical Content

Technical writers create a wide range of content or documentation, but they can all be classified into two major classes:

  • Developer documentation; usually more technical in nature and targeted towards developers within an organization or developers using a particular software or tool.

    Their aim is to help the developer easily understand and navigate the technical parts of a software or tool in question, including its structure and architecture. A lot of internal docs (written by a technical writer for use within the organization) fall in this category. Other types of developer documentation include:

    • How-to guides

    • Tutorials

    • Knowledge base

    • API documentation

    • Internal guides

    • Technical reports

    • Administrative docs

    • Technical articles

  • User documentation, usually less technical in nature, are targeted towards the non-technical users of a software or product (also known as the end users), and doesn’t involve a lot of technical jargon. They serve as guides to help the user understand and navigate through the technology in simple ways. They can be instruction-based (such as in tutorials, user guides, JIT (Just-In-Time) documentation, and how-to-guides for certain features; or they can be explanatory, like FAQs (frequently asked questions), blog posts, or concept articles.

Possible Technical Writing Career Paths

Having really strong technical writing skills can also help you land other roles besides the conventional 'Technical Writer' title.

  • Developer advocate: These are people who create documentation, tutorials that include sample code examples and sample repositories for that software, blog content, as well as video content to make sure that anyone who uses it has all the information they need.

  • Technical Documentation Officer: Technical Documentation Officers are focused entirely on creating and managing documentation. Most times, this could be internal documentation (within the organization) or external documentation.

  • Technical Content Writer: Technical content writers collaborate with the marketing department of an organization to create articles for a target audience, mostly developers. These articles are usually aimed at stimulating interest in its software products or services.

Getting Started: Essential Skills and Tools

Needed Skills

Being a technical writer writing requires a different skillset compared to other forms of writing. Here are key skills every technical writer needs:

  • Research: As a technical writer, you will always deal with new technologies, new tools, and new processes. You have to develop a passion for research on the unknown. Researching ensures accuracy in your documentation, while helping you to fill your previous knowledge gaps.

    Whether it's a different programming language or an API for a new platform, you have to set out time for research. This is a point that cannot be overemphasized.

  • Analytical/Communication Skills: As a technical writer, you must be skilled in breaking down complex processes and concepts into easy to follow instructions and explanations, being able to convey them simply. Knowing your target audience (see above), you must know how to identify areas that need explanation, break down complex processes into easy to follow instructions. Identify areas that need explanation and use plain language that is easy to understand.

  • SEO: As a technical writer, this skill makes you write articles that can be easily found on Google and other search engines in a way that is both understood by humans and properly indexed by search engine crawlers.

  • Technical Skills: Finally, you need to have corresponding tech skills. Understanding technical terms and knowing when to use a word, concept, or highlight a process is very important; which is where basic coding skills come in. Having basic knowledge of programming and development concepts helps you in relating with the developers you interact with, and allows you to test out the features and tools you write about.

    As you'll be working with different tools and programming languages from time to time, a foundational understanding of software development and one programming language will help you easily understand others.

  • Visual Image Skills: Most technical documentation are either explanations, tutorials, or guides; so visual elements are important in order to bring further clarity in your documentation. Things like screenshots are important in tutorials so the readers can use them as a reference point while carrying out the instructions in the doc.

    Diagrams and flowcharts are important in more explanatory technical documents. It would serve you well to know screenshot tools, basic design principles, and know how to create simple but attractive visuals; in order to increase readability and comprehension.

But what if I don't have a technical background?

Many people with a fascination for technology want to pivot into technical writing as an intersection of their skills and passions. Like you, some of them may not have a technical background, and that is not a problem. If you don't have any coding experience, you can easily get acquainted with basic programming languages like HTML, CSS, and JavaScript from websites like w3schools, Codecademy, FreeCodeCamp and Youtube.

Here are some introductory courses you can take as you learn these languages:

If you still think you don't need to learn how to code, these words from Linda Ikechukwu of Everything Technical Writing should make you rethink:

Most people like to argue that this is not important, but I disagree. As a technical writer, you'll often be required to create content that clarifies how a programming concept or a piece of code works. Even if you'll be woqrking with a different set of languages, tools, or technologies than what you're used to, some experience of how one programming language or one tooling works, will help you learn another faster.

Linda Ikechukwu, technical writer, software developer, and developer advocate.

Tools of The Trade

Here are some essential tools that you'll need to master in your journey as a technical writer:

  • Markdown: This is a lightweight markup language for formatting text in technical writing, using plain text. It is simple to learn and creates well-formatted documents with ease.

  • Help Authoring Tools: Specialized platforms like MadCap Flare for authoring, managing, and publishing technical documentation.

  • Collaboration and Version Control Tools: As a technical writer, you'll be working a lot with developers. Version control systems like Git help to not only review code, but also document revisions to code as those changes occur, as well as collaborate with developers and other technical experts who already use that environment.

  • Style Guides like Google Developer Style Guide, Microsoft Style Guide, or the style guide of the company you are employed in as a technical writer. Adhering to these guides help you refine and properly align your writing for technical and non-technical audiences.

Getting Started: Steps to Learning

Courses, Trainings, and Certifications

While you do not need a university degree to start a career as a technical writer, technical courses help you learn the basics in a structured format. As a beginner, here are a few introductory courses you can take as a beginner to help kickstart and guide your technical writing journey:

Practicing

A good way to start practicing is to start writing as you learn.

Did you learn something new in your development journey? Write about it.

Did you encounter a problem while coding and you found a way to fix it? Write about it.

Are there basic technical concepts or tools you wished someone had taught you about? Write about them, and don't forget to include the Important things you think other writers glossed over!

If you're more interested in internal/external documentation, you can learn to practice and get documentation experience by contributing to open-source projects, or programs like Google season of Docs and Outreachy Internships.

Building A Portfolio… In Public

As you practice writing about these concepts, make sure to publish them on well-known developer platforms like Hashnode or Dev.to.

That way, you get to share your writing with a wider audience (which increases your chances of getting noticed), and include your best published articles in a portfolio, which becomes extremely valuable when applying for jobs.

A good tip is to publish across both platforms, and maybe more (called cross-posting); to get even wider coverage.

Technical Writing Tips…

Audience Analysis: This is one of the biggest factors to consider as a technical writer. A good technical writer always writes in a way that considers the target audience. An article targeted at beginners, for examples will not be the same as documentation meant for late intermediate or experts. They will be written and structured differently.

One way to weave this factor into your work is by outlining any necessary prerequisites at the beginning of your articles. This way, readers your know the level of knowledge (of products or concepts) that they need before going further in reading your article.

As you write consider these questions:

  • Who am I writing this for?

  • What do they need to know about this technology/product? What terms will they be searching?

  • Why/where will they be reading?

Document Structure/User Experience: Now that you know your audience, you need to think about the documentation itself, and how readers experience it. You need to ask questions such as:

  • How will this documentation meet their needs?

  • Is it easily navigable?

  • Does it have a glossary? (If the post introduces multiple unfamiliar terms)

  • Is it accessible? Am I considering people with disabilities?

These are factors you constantly consider as you create and review your documentation.

Research and Testing: Thoroughly research the concept, product, or technology you want to write about. Speak to developers, do a lot of online search, and carry out your own tests with it (especially if you're creating tutorials and how-to guides) in order to provide deeper insights, a greater level of assurance (as you've tested it yourself) and also provide visual aids.

Feel free to draw references for your work from previous documentation by other authors in a way that does not plagiarize.

Now I Need A Job…

This is usually one of the hardest parts of your journey as a technical writer. After learning the tools of the trade, and making sure you have a fairly good portfolio; you still have to apply for jobs. You've done the work, now all you need is to be given a chance.

Here are a few places you can check for technical writing gigs and jobs:

Technical Writing Gigs/articles

Job boards

Communities

Being part of communities can also be essential, not only to getting jobs, but also in receiving feedback, tipis, or even recommendations from other writers and technical experts in the community.

Conclusion

Technical writers are highly valued specialists that fulfil very important tasks within the software development ecosystem. With documentation, they help onboard internal and external users of a technology with guides, tutorials, and other forms of specified documentation. As a technical writer, you are teaching developers and non-technical users how to use new technologies, navigate projects, and use software.

As a beginner, getting started is not as difficult as you think. All you need to do is to learn, get started and practice. Practice by documenting what you learn, practice by creating new documents for existing programs or projects, practice by improving the documentation of an app you love to use. Interact with communities and share your documentation online to receive feedback.

Whether on your own blog, or in an open source contribution, the more you practice, the better you get; building your portfolio and gaining experience. Good luck!

Further Resources

Here are other resources that will assist you in your journey as a technical writer:

technologyTechnical writing beginnerwriting