Technical writing in open source

We're always interested in learning from professionals in the industry, especially in technical writing. So when we learned David Both, author of several books about Linux and open source including Using and Administering Linux: 2nd Edition was working on an update to his book series, we wanted to learn more. Thanks to David for this insightful interview about his process and how he started writing:

As always, let's start with an introduction

First, thanks for your interest. I appreciate the opportunity to discuss my work with you.

I am David Both. I was the kid who fixed the neighbors' computers. The nerd wo carried my AP Chemistry book and slide rule under my arm. I've always been interested in STEAM—yes, including the Arts.

I've been working with computers since 1969, and Linux since 1996. I like to build my own computers, partly so I won't have to pay the Microsoft tax. Well, except for the laptops.

I hate to see old computers—or not so old ones—discarded as if they were useless. I sort of collect them, install Linux on them and either use them myself or give them away. My oldest computer is twenty years old and still running top speed on the most current version of Fedora.

You wrote the Using and Administering Linux series of books. What were the books about?

These books are about helping people become users and supporters of Linux. By that I mean someone who supports Linux computer systems when they break or the user needs assistance. They're about me paying forward the help I got from friends and family when I needed it, and the support, training, and guidance I got from many mentors as I came up in the world of computers.

I like to share my knowledge and experience and I did training for IBM for several years, and I've done Linux training for many years. I don't teach in-person courses any more so these books are a way to move my training courses out of the classroom and into the students' own environment.

What is your process to write a book series like this? Do you start with research? Or do you have it all in your head and it's a matter of getting it out there?

The problem was that I couldn't keep it all in my head as there was too much and I used much of it too infrequently to remember accurately.

I first started by creating a hand-written hardcopy document as a memory aid for problems I'd encounter in my work. It soon became obvious that I needed to do something better, so I created a digital document using StarOffice, the parent of LibreOffice. Some of my consulting customers thought they's like to have access to that information, so I launched my first website.

That collection of information ultimately became the basis for many of my books.

Of course I do a lot of research for my books. That's important even for new editions like the 3rd Edition that I'm now working on because things do change. One example is that some of the basic Unix / Linux commands have changed. For one example, the dmesg command no longer allows regular users to display the kernel messages; only root can do that. This is a security enhancement, which is good, but it breaks some of the experiments.

What's your process for revising a book series like this? Do you start with questions that people have sent you?

Some of the updates I'll include in this edition are the result of questions I've received from students taking the course. Others are from students who notices a specific problem, found their own circumvention, and have passed that along to me for inclusion.

I've collected a number of those on the Errata pages on my website.

You mentioned that you have some corrections and rewording in the 3rd Edition. What other changes or updates are you planning?

There are some significant changes in the Fedora installation ISO images. The primary one is that all but two, the Server and the Everything, only create BtrFS filesystems without any options for other filesystems. I neither like BtrFS, nor do I trust it. For various reasons I much prefer using Logical Volume Management partitions with EXT4 filesystems. It's also LVM and EXT4 that's most likely to be found in many organizations that use Linux. While BtrFS is fine for some use cases, it most definitely fails in many others.

As a result, I've switched from using the Fedora Xfce ISO, to the Fedora Everything ISO which offers many options, including more choices for filesystem, and a massive number of choices for configuring the applications and tools to be installed. It's very much one from "Column A" and as many as you want from "Column B."

For example, I can choose the Xfce desktop in "Column A." Then I can choose one or more other desktops, LibreOffice, scientific tools, server tools, additional command line tools, and more.

Other changes include additional security for command some line tools that no longer work as they did in earlier editions. so I need to change the experiments affected by that. And I am also looking for places that need rewording for clarification and elimination of some redundancies.

How did you first get interested in writing books?

I've always been interested in books and writing. I was fortunate to have an amazing Composition teacher in high school, Miss Olive McHugh. I learned a lot about writing from her and put that to good use when I was with IBM.

When IBM moved me to Boca Raton, Florida, my job was to write training documentation for new hardware using both in-person and self-study course formats. We had a strict formula we used:

1. First create a set of objectives.
2. Generate questions that test the objectives.
3. Write the course body materials that teaches the objectives.
4. Test the resulting course.
5. Make changes as required.

When I had my own business consulting and training, I followed this formula with great success.

Then, as I said, I took all the notes I used as memory aids and started posting them on my web site. By that time I had also started writing for Opensource.com. Much of what I wrote about was not just how to do things but why and much of the history and reasoning about how Linux (and Unix) were designed and why work as they do.

Between the two web sites, I had a lot of material, so I started thinking about writing a book based on all that information.

I attended All Things Open in 2017 and was fortunate to find the Apress booth. I met the Acquisitions Editor there, and told her that I had a book for her. We went to a nearby cafe and discussed it. She liked the concept of The Linux Philosophy for SysAdmins, and I signed my first contract soon after that.

I now have written nine books for Apress, and am working on books 10 through 13, which is the 3rd Edition of my Using and Administering Linux series.

What is your preferred tool or software to write your books?

I have a Word Template that Apress sent me the when I was working on my first book, but I have made a few minor changes to it. I saved it in OTT format, which is the Open Document template format used by LibreOffice. I use that to start each chapter using LibreOffice Writer.

I create all the chapter documents using that template, and save the works-in-progress in ODT, the Open Document format. When each chapter is done, I save them in ODT, DOCX, and PDF and upload all three versions to Apress. The production department generally uses the DOCX version, but they refer to the PDF version when they need to verify what a table, list, image , or data stream should look like in the final production copy.

One reason I like LibreOffice is that it can export directly to both DOCX and PDF, as well as several other formats, without the need for any additional software.

This image was captured while I was working on my previous book, systemd for SysAdmins.

---

Thanks to David for sharing his process with us. You can follow more of David's writing at Both.org, which is also a community website about all things Linux and open source. David's books include systemd for Linux SysAdmins, Using and Administering Linux – Zero to SysAdmin: 2nd Edition, and The Linux Philosophy for SysAdmins. David also co-authored Linux for Small Business Owners with Cyndi Bulka.