Like any activity, technical editing has its own set of languages and tools.
Technical writing today can happen in a variety of different programs and languages. As a tech editor, you need to be versatile and tech-literate because you edit where the writing is. If your author is a developer, they’ll write using the toolchain they’re most comfortable with. Tech editors today need to be comfortable stepping into a variety of different landscapes, and you’ll need your own tools for editing once you get there.
Tools for content
Writing programs and text editors
Technical writing today can happen almost anywhere: Google Docs, Word, an editable PDF, plain text editors, and any number of note-taking tools like Notion or HedgeDoc. I’m keeping a keen eye on Almanac but haven’t used it yet.
(I’m not mentioning documentation because that covers a whole universe of tools too large to list here.)
Languages and markups
Technical content is often created using a lightweight markup language. You can’t be fluent in everything, but it’s good to brush up on the basics so that you can add value when you edit (and not trip up on some of the semantic elements).
- Markdown and its various flavors.
- Plain text markups like reStructuredText (reST), AsciiDoc, DITA and HTML.
Also worth mentioning are static site generators (SSGs) like Jekyll, Hugo, and Sphinx. It pays to have a mental model of how some of the popular SSGs hang together so you can traverse a repo, fix a link, or understand how blog posts work on the site.
File sharing, version control platforms, and CMSs
How is your author sharing their files with you? It’s good to know your way around Google Drive and Dropbox.
You might be required to edit directly in a content management system (CMS) as part of a structured workflow. It’s good to have an understanding of some of these tools, like Drupal, Sulu, TYPO3, WordPress, etc. Also consider other content platforms like wikis (think Confluence) and knowledge bases (like Zendesk).
Tools for editing
Language checkers and linters
Style guides and dictionaries
There are a plethora of writing and style guides available today. Ultimately, what you edit to depends on the client, organization, or project; but it helps to have an awareness of what guides are out there. I like these curated lists by Write the Docs and Draft.dev which feature the biggies. See also the Conscious style guide for conscious and inclusive language.
Editing markup conventions
Last but not least, tools for the task of editing itself. You need to be aware of how to add suggestions and comments in different programs.
- In Word, are you using track changes?
- In Google Docs, are you working in suggestion mode?
- In GitHub, are you just adding commentary or are you making suggestions to the file?
The all-knowing editor
You can’t know everything all the time. There’s a lot of tech out there!
BUT, technical editors do need technical aptitude. Not only does it add to your domain knowledge, it makes you good at your job. If you feel comfortable with the technology you’re working with, you can get straight to work adding value to a written piece.
Further reading: Check out this great post by Chris Ward on the Knowledge Owl blog Tools for editing docs as code.
Image credits: Teacups image by NEOSiAM 2021 from Pexels.