Technical Writing for Software Developers E-Book

Chris Chinchilla

• Herausgeber: Packt Publishing
• Kategorie: Fachliteratur
• Sprache: Englisch

Seitenzahl: 265

Veröffentlichungsjahr: 2024

Beschreibung

Effective documentation is key to the success of products in remote software development teams, facilitating clear instructions that benefit the entire development team. Technical Writing for Software Developers lays a solid foundation of essential grammar, providing language tips and explaining how precise writing enhances documentation, and walks you through the fundamental types and styles of documentation.
Starting with an exploration of the current state of the tech writing industry and its significance in both the software and hardware realms, you’ll master the building blocks of technical writing, exploring tooling choices and style guides, and create dynamic multimedia-laden documentation. This book equips you with valuable insights into the writing and feedback process to ensure continuous improvement. Additionally, you’ll take a peek at the emerging trends and technologies, including AI tools, shaping the future of technical writing.
By the end of this technical writing book, you’ll have developed the expertise you need to tackle documentation requests effectively, armed with the knowledge of the best approach for documenting any topic, encompassing text, media elements, structure, and appropriate tools. The skills acquired will enable you to achieve seamless teamwork, enhanced project efficiency, and successful software development.

Leseprobe

Technical Writing for Software Developers

Enhance communication, improve collaboration, and leverage AI tools for software development

Chris Chinchilla

Technical Writing for Software Developers

Copyright © 2024 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author(s), nor Packt Publishing or its dealers and distributors, will be held liable for any damages caused or alleged to have been caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

Group Product Manager: Kunal Sawant

Publishing Product Manager: Akash Sharma

Project Manager: Prajakta Naik

Book Project Manager: Manisha Singh

Senior Editor: Rounak Kulkarni

Technical Editor: Jubit Pincy

Copy Editor: Safis Editing

Proofreader: Rounak Kulkarni

Indexer: Hemangini Bari

Production Designer: Prafulla Nikalje

Senior Developer Relations Marketing Coordinator: Shrinidhi Monaharan

Business Development Executive: Kriti Sharma

First published: March 2024

Production reference: 01220324

Published by Packt Publishing Ltd.

Grosvenor House

11 St Paul’s Square

Birmingham

B3 1RB, UK.

ISBN 978-1-83508-040-5

www.packtpub.com

To everyone in the many tech-writing communities I am involved in. Keep up the good work.

Contributors

About the author

Chris Chinchilla is a technical writer, blogger, video maker, and podcaster with over ten years of experience. He has worked on numerous large and small technical projects and products, helping them explain what they have built to the outside world. He is active in many tech writing and non-tech writing communities, helping mentor new writers. He maintains a handful of open source tools to help writers create the best words they can. In his spare time, he writes games, fiction, and interactive fiction.

About the reviewers

As an experienced technical writer and community leader, Segun Light Ige-Olumide is passionate about empowering developers and fostering growth within the tech industry. With five years of experience, he creates engaging content that addresses developers’ evolving needs. Segun has also led multiple successful developer communities, prioritizing collaboration, learning, and professional development. Committed to making a meaningful impact, he strives to contribute to the tech community’s ongoing growth and innovation.

Fortune Ikechi is a software engineer and technical writer with extensive experience in enhancing developer relations and community engagement. His commitment to innovation and community building and his ability to bridge the gap between developers and products have driven product adoption and awareness. Being a tech community advocate, Fortune continues to share his expertise and insights, contributing to a better understanding of technology’s potential.

Table of Contents

Preface

1

The Why, Who, and How of Tech Writing

Why should you care about tech writing?

What can documentarians accomplish?

Marketing

Product

Sales

Support

Developer relations

Engineering

Machine readers

Proofreading for accuracy and safety

Content silos

Writer in the middle

Understanding who you are writing for

Learning by example

Don’t forget the end users and the end-end users

Summary

2

Understanding Different Types of Documentation in Software Development

Templates

Getting started and onboarding

A detailed overview of Getting Started

Learning with an example

Templates for a Getting Started guide

Tutorials

Expanding on the example

Templates for tutorials

Reference

API documentation

Architecture and design details

Security and privacy details

Technical blog posts

Summary

3

Language and the Fundamental Mechanics of Explaining

Common reasons for not writing confidently

Not a native speaker

Intentionally vague

Marketing and product reasons

Reducing cognitive load

Inclusive language

How to improve your writing

Consistency

Involving the user

Keeping it short

Removing unnecessary words

Don’t show off – let the product speak for itself

Don’t repeat yourself

Inclusive language: in more detail

Overly negative language

Biased language

Gender

Out-of-date language

Summary

4

Page Structure and How It Aids Reading

Humans are not your only readers

The principles of good layout

A quick primer on the markup language of the web

Thinking about pages semantically

Lists

Paragraph breaks

Tables

Admonitions

Tabs

An example of a well-structured page

Creating documentation menus and navigation

Following menu patterns

Adding internal search

Keeping links working

Summary

5

The Technical Writing Process

Scoping and requirements gathering

What to document

Research and product testing

Drafting and re-drafting

Feedback, testing, and maintenance

Metrics and measuring success

Summary

6

Selecting the Right Tools for Efficient Documentation Creation

Topic-based documentation

Docs as code

Documentation in the browser

Choosing toolchains and tools

Why docs as code?

Selecting and using a markup language

Adding metadata to markup with YAML

Making Markdown dynamic with MDX

The key tools in docs as code

Text editor

Collaboration

Rendering

Helping less technical writers with headless CMS

Analyzing documentation performance

Analytics tools

Sentiment

Summary

7

Handling Other Content Types for Comprehensive Documentation

We are more than technical writers

Code examples

Deciding on a consistent example

Creating and organizing code examples

Testing code examples

Keeping an eye on prerequisites

Screenshots, images, and charts

Screenshots

Adding other images

Making images accessible

Animated GIFs and videos

What to make a video of

What to show

How to record

Audio

What to show

Recording

Interactive experiences

More than final words

8

Collaborative Workflows with Automated Documentation Processes

Striking the right balance

What is a style guide?

Developer-friendly style guides

Choosing a type of tool to use

Automating image generation

Using test suites

Automating other image types

Automating video

Converting terminal commands to video

Other video automation options

Automating code testing

Other automation options

Converting file formats

Accessibility

Summary

9

Opportunities to Enhance Documentation with AI Tools

A brief history of AI

Understanding AI and ML

Recent advances in AI

Text and code completion and improvement

Generating documentation

AI for audio and video

Generating media

New ways of interacting

The principles of training and creating your own AI

Writing for robots

Summary

Index

Other Books You May Enjoy

1

The Why, Who, and How of Tech Writing

Tech writing is fundamentally about helping people understand concepts that are potentially complex or new to them. To do this effectively, before you start putting fingers to keys, you need to start by asking three key questions about your subject and the audience(s) for it. After doing this, later and more in-depth parts of the process will become clearer and easier. There are more audiences for your words than you might think, and different audiences have different expectations and needs from documentation. Understanding these will save you hours of work and countless frustrations later. Finally, to help you through those frustrating times, I hope to help you understand how important good tech writing is and what a crucial role you play, whatever the nature of your work is.

This chapter covers the following main topics:

Why tech writing is importantWhat documentarians can accomplishHow to understand who you are writing for

Why should you care about tech writing?

What’s one of the first things you look at when evaluating a new project or service? If the documentation isn’t the first thing you look at, I bet it’s in the top three. The primary function of documentation is to tell people how to use something, but it also has several crucial secondary purposes that provide value across a company or project team.

To quote a phrase I’ve used for a while in presentations:

“Documentation isn’t just for developers.”

Documentation gives confidence in a product making it useful for marketing sales enablement, customer support, search engine optimization (SEO), and, as we now realize, for myriad other machine-driven purposes.

This section reinforced what you probably already know and feel. After all, you’re reading this book! But how can you convince others of the worth of good documentation?

What can documentarians accomplish?

Tech writing often sits between and crosses over multiple teams in a company or project. This means that you have the potential to impact the work and goals of many, even if it’s not in your initial job description. This section covers some of the most common teams and departments you might encounter.

Marketing

If a project’s documentation is open to the public (not behind a login), it likely fuels a high percentage of searchable text on a website. High-quality, well-written documentation optimized for SEO is a goldmine for search engine traffic. No one wants to read documentation stuffed full of marketing content and working closely with a marketing team to ensure style consistency and break down content silos is essential.

Depending on the size and structure of your company or team, documentarians and marketing teams can work closely together to help this process. You can collaborate on style guides, write technical blog posts, review or edit white papers, and so on.

Product

I’m sure many of you know that good documentation can’t hide or improve a bad product. However, for the most part, products and documentation are somewhere between fantastic and terrible. Good documentation brings confidence in a product to a potential customer or user. Later chapters in this book will describe how to make your writing more confident, and this is one of the justifications for that style of writing. Often, someone decides between product options by reading their documentation. The products that sound confident and can do what their documentation promises are likely to appeal more to potential users.

Sales

Sales and sales engineers often have some of their own playbooks and content for working with current and future customers. However, much like with marketing teams, documentarians can work closely with them to ensure materials are consistent and break down those omnipresent content silos.

Support

Customer success, support, or whatever a company calls the team of people who help users achieve their goals are often any documentation team’s biggest allies and sources of knowledge. They see how people try to use a product daily. They know where users struggle, what they find confusing, and the common pitfalls they face. These teams also likely maintain their own sources of information or documentation. Again, try to work with them to reduce these silos, but regularly syncing with them gives you a great source of information for what documentation is missing and how effective current documentation is.

Developer relations

Though they are often part of sales or marketing teams, developer relations teams are typically out speaking with developers, convincing them, and helping them use a product. The content they produce could be one of the first things that a potential user sees, so again, work with them to ensure consistency of message, reduce silos, and much like support, find out what they feel is missing from the documentation that would help users.

Engineering

Fundamentally, documentation exists to make what product teams created understandable. Or, as I like to say:

“Documentation makes engineering look good.”

If you’re reading this book, then you’re probably an engineer. So, I phrase this section slightly differently from the other teams’ sections. Documentarians need to get details from engineering to explain how a product works and how to use it. There is frequently a disconnect between what engineering thinks is important, what documentarians think is important, and what users think is important. I dig deeper into this topic throughout the book, but briefly, cast aside your assumptions and in-depth knowledge and think about how someone completely new perceives what you have built.

Machine readers

It may or may not surprise you that much of the traffic to your documentation probably doesn’t come from human readers. Website scrapers, sitemap builders, and a variety of other machines trawl your documentation regularly. While documentarians are typically aware of SEO, the implementation of best practices can vary. This is another perfect opportunity to work with marketing teams to improve the visibility of documentation and surface it to potential customers even more than it already is.

However, SEO and “traditional” crawlers are old news. The new machines trawling your documentation in great numbers are feeding training data for large language models (LLMs) (https://en.wikipedia.org/wiki/Large_language_model). Whether you like this or not, if your documentation is public and for a moderately high-profile product, then until we agree on a standard way to block this happening, it’s probably already too late. I cover the rapidly changing topic of artificial intelligence (AI) and documentation in greater detail later, but right now, be aware that an increasing amount of people are interacting with the words you write in myriad ways.

Proofreading for accuracy and safety

Unless my memory fails me, I have never worked documenting any “mission-critical” product. There were undoubtedly products that were very important to customers, and any downtime or poor information would impact their business. But typically, any product issues are covered by service-level agreements (SLAs) (https://en.wikipedia.org/wiki/Service-level_agreement), which don’t often cover documentation issues.