Documentation is fundamental to helping potential and current users understand the amazing projects you build. For many developers and other technical-minded people, documentation is a challenging chore. Technical Writing for Software Developers covers all the important points you need to know to make great documentation easier and suited to developer workflows and tools.
Before I begin, I’d like to start where I always like to begin, with some history.
My grandfather worked for a long-since-acquired company that created and laid submarine cables, the long and large network of cables lurking under the sea that enable communications between countries worldwide. When he laid them from the back of the large ships that ran between the UK and Canada, he was laying gigantic reams of copper wires mostly meant for telephone and telegram traffic. By the time he retired, the internet existed in some rudimentary form, telephones were widespread, and he gave me a nugget of advice that I still remember today, despite being too young to really understand what he meant:
And he was right. Now, there are more submarine cables than ever, shuttling petabytes of data back and forth per day. Our work and play rely so much on a relatively small amount of vulnerable wires that rest on the ocean bed, are prone to damage and attack, and have disconnected smaller nations from the world.
I digress. Why am I telling you this in a book about tech writing?
My grandfather started his professional career as a technical artist. He drew up plans and instructions on how to make and lay these essential cables, plus how to use the machinery needed for the task. I can’t imagine he ever anticipated much of the work you and I do now (he died in 2001), but I could imagine that he would be amused that we ended up in related careers and fascinated by some of the projects I have worked on.
My point is that if we consider “technical writing” to mean explaining something to someone else so they can understand it and how to use it to accomplish their goals, then “technical writing” is everywhere.
Safety instructions, appliance, and furniture manuals, online tutorials and guides, books, technical blogs, high-risk equipment installation instructions, and even board game manual instructions are forms of technical writing.
This book is aimed at software developers who want to learn how to explain better what they build. It doesn’t intend to cover all the examples above. However, as with many complex topics, sometimes it’s important to understand how we got where we are today and the gamut of related work that others undertake. My grandfather was also more of an engineer at heart at a time when qualifications were more necessary but harder to get if you came from a poor family like he did. But he was passionate about helping those around him understand complex technical topics. One of his proudest moments was captured in a tattered old black and white photo of him explaining how the cables worked to a young Prince Phillip (the last English Queen’s husband). I studied computer science and spent several years in development teams before realizing I enjoyed explaining technical topics more. In short, you’re in good company!
Ok, I’ve explained what technical writing is, but that doesn’t always help. Sometimes, when figuring out what’s expected or typical in a role or task, it’s easier to look at what it doesn’t include.
I should say that many of these potential tasks depend on the team’s size. As possibly the only person on a team or project with the ability or desire to communicate and explain, you may find yourself called to undertake tasks you never anticipated. You might be OK with doing them all, and that’s OK. But maybe you’re not OK or don’t have the time and the inclination, and that’s also OK. What I present in this section attempts to get to the core of what technical writing work should be, so you shouldn’t feel you have to do any of the other work.
Many people you speak to hear “writing” and think you want to edit their website copy or other assorted text tweaks. Depending on the topic and the project size, you may still be interested, and the best-suited for the task, but technical writing is generally specialized and requires niche technical knowledge. In short, you’re probably not the most suited and are too expensive for the job.
I have worked on some teams where technical writers handle the text that appears on buttons and in Command Line Interface (CLI) commands, and for a product aimed at developers, it can make sense. However, there are probably people more suited to the task whom you can instead advise.
I need to be careful here. I blog a lot because I like blogging, and there is also great demand from marketing departments at technical companies for people who understand the technology to help them spread that word to other technically minded people. Marketing teams will be very happy if you do want to blog, but it doesn’t suit everyone, and you don’t have to feel obligated.
This is another one where I don’t help as I also run my own podcast, reporting on events and interviewing people in the tech industry. A technical background has helped me a lot with some subjects, and learning to write more clearly has also helped me produce clearer content. However, most tech journalists I encounter aren’t that technical, and I have frequently taken issue with the level of misunderstanding in some tech reporting and feel that we should consider much of what we call “tech journalism” to be more “consumer journalism”. I doubt many of you reading this book will be asked to tackle any tech journalism, but surprisingly, it’s what many think of when you mention “technical writing”.
Technical writers are often shuffled back and forth within the corporate structure and occasionally become part of marketing teams. However, technical writing should only cover facts (more on that in Chapter 4, Page Structure and How It Aids Reading), and you shouldn’t ever feel compelled to write press releases or any other pure marketing copy.
Technical writing is any media, mostly words, but not always, that explains to someone how something works and how they can use it. This could be as little as a README file, code comments, or as much as pages and pages of tutorials and reference material. I laid out what tasks I consider to be outside of that definition, but some are more outside of it than others, and if there’s one piece of advice to take away from this section, it’s this. Your task is to find the best way to explain complex topics. You will learn through this book and, over time on your own, the best ways to do this that work for you and your audience.
Hey there! That last section told you a little about me, but my name is Chris Ward. More typically known online as “Chris Chinchilla,” as my real name is so common in English that no one would ever find me. At the time of writing, I live in Berlin. However, I was born in London and spent a long time in Melbourne. I have a degree in Multimedia Computer Science. After completing my studies, I played in bands for a few years before settling into the classic programmer job of the early 2000s, building websites for early e-commerce businesses. I built many of these sites in Drupal, which exposed me to open source software. Drupal was quite ahead of its time in many ways, especially when it came to the community. I enjoy programming, but I realized relatively quickly in my career that I don’t quite have the mindset to be an excellent programmer. At Drupal community events, there were often activities for people who don’t code, and I started contributing by summarizing issue discussions and writing documentation. I was much better at this and had never realized it was a job people would pay you to do! Over the years after that, I moved in and out of technology ecosystems and between roles in tech writing and editing, tech blogging, developer relations, and more. Also, typically, I have a couple of side projects along the way.
People who are good at explaining topics often sit between and have experience in different disciplines and roles. A good tech writer often has engineering, support, design, product, and marketing exposure and can help bring insights between these teams. In short, no matter your experience or your journey to get that experience, if you are keen to help people understand, then technical writing is the place for you!
This book is mostly aimed at developers who want to learn how to explain their creations to the world better. However, anyone involved with a technical product can find something useful here. And for any of you reading who are already writing documentation, welcome! I think you will also find enough new information to make this book worthwhile reading, especially from Chapter 7, Handling Other Content Types for Comprehensive Documentation onwards.
Much like the terms developers, engineers, and programmers, practitioners in this field also refer to themselves in ways that are mostly the same but mean different things to those who use them.
The two main terms you have likely heard used interchangeably are “technical writing(er)” and “documentation”, plus maybe some other terms appended. These terms mean more or less the same thing, at least more so than with programming-related role titles, but many of us still take issue with them and prefer other, more inclusive terms.
For example, as I will cover in Chapter 8, Collaborative Workflows with Automated Documentation Processes, a lot of technical explanation is far more than words these days, and our typical titles reflect a rather out-of-date viewpoint. I also believe that a documentation portal may not always be the best place to explain everything. I experimented with “technical communicator” (which I still have on my LinkedIn profile at the time of authoring this book). I’ve also heard “documentation engineer”, which I quite like as it reflects that many of us at smaller companies also build a lot of tooling for documentation. However, what a lot of technical writing communities have settled on to include everyone is “documentarian”. It’s not perfect, but it reflects that not everyone who contributes to or cares about good documentation has a full-time role dedicated to that task. I assume, much like many of the readers of this book. So, that is the term I will use to refer to you and us throughout the book. Concerning our work, I will use the most relevant term to suit the use case and output. For example, documentation, blog posts, videos, and so on.
I will also use the terms “project” and “product” somewhat interchangeably to refer to what you are documenting. In my mind, a “product” is something commercial, whereas a “project” might not be. However, a few caveats and small differences aside that I will address when I get to them; they are essentially the same.
At the time of writing, the tech industry generally finds itself in an interesting place. The years of wild spending and tech startup valuations are behind us. The unstoppable growth of tech has slowed, and the industry can no longer do whatever it wants and expect no one to question it or everyone to accept it.
No matter what happens in the rest of the tech industry around us, one statistic glaringly remains in survey after survey of developer opinions and ecosystems. People want and need better documentation. The race to build over the past few years led to a plethora of applications that may or may not be well built, but often don’t make a lot of sense to internal or external users. There are budget cuts in the industry at the moment, and sometimes, roles outside of engineering are some of the first to go. But if you are open to learning and learning how to learn, there will be a role for you for a while.
It would be naive and dishonest of me to tell you that the industry isn’t in the midst of a massive state of change. The last chapters of this book will cover AI-based tools that have swept through everything in the past year or so. It remains to be seen if they are the game changer everyone promises or just another ride of the hype rollercoaster, but there’s no doubt that they will affect how we create and consume documentation in the medium term.
Automated tools for generating some parts of documentation have existed for a while, but the new wave of AI-powered options is definitely more powerful and nuanced than anything before. They can’t cover the complete documentation requirements yet, but they can fill many gaps and needs. With regards to the state of the industry and our role in it, even if everyone decides to replace their documentation platforms with AI-powered bots, they still need someone to write the source material that feeds the AI for a while. We may write less for direct human consumption, but we will still be writing.
This book is aimed at those who primarily code, be they developers, support or sales engineers, or existing technically minded technical writers. It’s full of advice, tips, and tools to make documentation the best possible with minimal work.
If you’re reading this book, you are someone who cares about explaining complex topics in the most effective ways. You may already be an experienced documentarian looking for new ideas and a knowledge top-up. Or maybe you’re less experienced but want to do something to improve the current state of a project you contribute to. Whatever your motivation, there will be something for you.
I intend to take you on a journey from teaching you the essentials you need to know to exploring cutting-edge ideas and practice to raise what you create head and shoulders above other projects and products.
Chapter 1, The Why, Who, and How of Technical Writing, talks about all the different stakeholders with an interest in good documentation and what it can accomplish for them.
Chapter 2, Understanding Different Types of Documentation in Software Development, explores the different documentation types that can form documentation.
Chapter 3, Language and the Fundamental Mechanics of Explaining, covers the grammar fundamentals that make documentation clearer and more confident.
Chapter 4, Page Structure and How It Aids Reading, explains how page structure makes content easier for readers.
Chapter 5, The Technical Writing Process, advises on the ideal process to follow for collaborative technical writing.
Chapter 6, Selecting the Right Tools for Efficient Documentation Creation, discusses the options and how to pick the tools to help create, collaborate, and provide documentation to readers.
Chapter 7, Handling Other Content Types for Comprehensive Documentation, explores other types of media to add to documentation that complement your words.
Chapter 8, Collaborative Workflows with Automated Documentation Processes, delves into how you can automate many common processes in creating documentation.
Chapter 9, The Opportunities to Enhance Documentation with AI Tools, talks about how the new wave of AI tools can assist and enhance documentation creation.
There are a number of text conventions used throughout this book.
Code in text: Indicates code words in text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles. Here is an example: “ For AsyncAPI, you use user and signedup.”
A block of code is set as follows:
var schema = buildSchema(`
type Query {
hello: String
}
`) Tips or important notes
Appear like this.
Feedback from our readers is always welcome.
General feedback: If you have questions about any aspect of this book, email us at customercare@packtpub.com and mention the book title in the subject of your message.
Errata: Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you have found a mistake in this book, we would be grateful if you would report this to us. Please visit www.packtpub.com/support/errata and fill in the form.
Piracy: If you come across any illegal copies of our works in any form on the internet, we would be grateful if you would provide us with the location address or website name. Please contact us at copyright@packtpub.com with a link to the material.
If you are interested in becoming an author: If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, please visit authors.packtpub.com.
Thanks for purchasing this book!
Do you like to read on the go but are unable to carry your print books everywhere?
Is your e-book purchase not compatible with the device of your choice?
Don’t worry!, Now with every Packt book, you get a DRM-free PDF version of that book at no cost.
Read anywhere, any place, on any device. Search, copy, and paste code from your favorite technical books directly into your application.
The perks don’t stop there, you can get exclusive access to discounts, newsletters, and great free content in your inbox daily
Follow these simple steps to get the benefits:
https://packt.link/free-ebook/9781835080405
© 2024 Packt Publishing Limited All Rights Reserved
