Technical editing in a community

Seth Kenlon is a longtime technical writer and open source contributor. We've interviewed Seth before about his perspectives on technical writing and how he got started in writing about open source software. Seth is also part of Both.org, a new article-based community website about Linux and open source software. We asked Seth about his role there and what it's like to serve as editor.

You've been a technical editor for some time, in different capacities. What is that like?

People tell me that I have a knack for explaining complex concepts in a relatively simple way. In 2016, I got hired by Red Hat to help build training courses, and later I joined the team managing a blogging site called Opensource.com - discontinued now, but happily its content remains online.

During my tenure as technical editor, I had the privilege of reading literally thousands of articles, and the further privilege of working with authors to ensure that the articles were accurate and clear. I do the same thing now in a volunteer capacity for the Both.org tech community.

At Opensource.com, you served as both technical editor and Technical Community Advocate. What was that role about?

As the Technical Community Advocate, it was my job to ensure that authors were getting real benefits from their contribution. The site's supporting company was paying all the bills, which was amazing, but all the authors were contributing as volunteers. I was tasked with ensuring that the authors were getting out of that deal as much as, or more than, they were putting in.

To do that, my team and I turned the spotlight on the author. That's easy to do, because every contributor in more than twelve years of the website was essentially a subject matter expert. You don't have to know everything to be an expert, because nobody does. Even when you're writing your very first article ever about the simplest Python "hello world" script, you're a subject matter expert on being a new Python programmer. As popular as Python is, most people in the world are also new to it, so that new author who hasn't even discovered what a function is yet has a lot of valuable information to share.

When I edited an article, I looked for places where it could be more succinct. I looked for places that needed to be simplified for clarity. And of course, I tested everything and shared my findings with the author. It was an amazing experience for me - and I hope for the authors as well.

Now you're also volunteering as an editor at Both.org. What is your role as editor like?

Well, first of all: the most important thing about technical articles is that to be effective, they have to render success. If you look up "how to exit Vim" and find twenty articles about it, the best article is the one that works. It can be overly verbose, it can have atrocious grammar and spelling - but as long as it gets you out of Vim, you're happy.

We see proof of this today with ChatGPT, which just makes up answers half the time. But because they're expressed in a way that asserts authority, people accept them. But anybody who's tried to get ChatGPT to write code for them knows that just because something is very nearly right, it doesn't mean it actually works.

For Both.org, it's my goal to ensure that articles are accurate. I don't necessarily have the luxury of rewriting each sentence three times until I find the most efficient and clearest way to express an idea. But as long as the article ends in success, then I think Both.org is bringing real value to the tech community.

Of course, there's room for "water cooler" chat on Both.org, too. Not every article has to have a point other than musing about updating RFC 527. I love idle tech articles, and for those kinds of articles I scrub them for grammar and spelling and then give them the stamp of approval.

What skills does someone need to be a good editor?

First, I look at an article and try to understand what single task it's trying to achieve, even if that single task has two or three stops along the way. For instance, an article about "how to install Wordpress and share it with the world" actually involves installing Wordpress, configuring a web server, and opening a port in your firewall, but there's still only one driving point to the article.

If there's not a single point to an article, I tell the author that it needs to be two (or more!) articles. In Linux, we have the saying "do one thing and do it well", which is really just a fun way of supporting modular design. An article, in my opinion, should do one thing. If you want to do more than one thing, write more articles and string them together.

Having established the singular point of an article, I then look at each paragraph. It may not seem like it, but technical editing is a form of programming. The English language (in my case) is the code, and the paragraphs are the functions. A paragraph has an input and an output. The input is generally the previous paragraph. The paragraph's outcome is its output. If a paragraph hasn't changed your input state, then there's the probability that the paragraph isn't necessary. A good [bad] example is the paragraph above this one. I'd already made my point that an article should only do one thing, but then I wrote a whole other paragraph that reiterates the same principle. Were I editing this interview, I would delete that paragraph, and I wouldn't apologize to the author for it.

After determining the validity of a paragraph, I turn my attention to the sentences within the paragraph. Sentences are the lines of code that build the function, and usually the less logic you include, the less chance there is for failure. I like short sentences, and not too many of them. I tend to cut out adjectives and adverbs. I cut out conjecture and most of any opinions or idle musings.

It's programming with natural language, in the attempt to create a set of instructions that a human can follow to achieve the exact same outcome, every time. It's a recipe, or a game.

Here's a fun question: What's your top editing pet peeve?

The process of technical writing often involves fits of inspiration combined with frantic research, trial and error, and revision. If you dare edit the result of that, then you must be ready to accept anything. At the time of writing, that particular choice, however bad it might seem now to you as the editor, really did make sense to the author.

Saying that another way: everything is my top editing pet peeve. As an editor, nothing's ever written well. And no matter how hard you try, you'll never be able to make it foolproof. Such is the human condition!

Thanks to Seth for sharing his insights about technical editing. You can follow the new open source community at Both.org.