Software developers use a wide range of tools to craft their code: lexers and linters and, compilers and transpilers, task runners and unit testers. To name a few.
The ultimate aim is to increase quality without increasing time and effort.
High quality code is well-structured, well-documented and highly legible. It conforms to standards and conventions, avoids repetition and is concise without becoming obscure. Much like good writing.
As writers we're not left behind in the dust. There are several developer-oriented tools out there that we can use in our writing process. Here are some of the utilities we adopted. They're all free, open source tools by the community, for the community.
Markdown is a lightweight markup language with simple text formatting syntax. It's easy to learn and remember, and it stays machine-readable so software can understand the markup too.
This means you can make your content pretty and useful without locking down the layout or formatting. Once you're happy with the content you can convert it into html, PDF, Word, LaTeX, or any other target format with an open standard. Your source format stays plain text, so it can be edited in any kind of text editor, including web-based WYSIWYG editors such as TinyMCE and CKEditor.
If you stick to using plain text, markdown or a similar text-based markup language, any text editor will do. Some are better than others depending on which operating system you use and whether you prefer shiny GUIs over screen-oriented "unixy" editors such as vi and emacs.
We've settled on Atom Editor, a modern open source text editor built by the folks at Github. It's fast, clean and comes with a bunch of available packages (plugins) contributed by a thriving community.
We like the markdown preview package to allow for a split-screen preview of what you're writing. Linters
Here's where things get interesting: linters are tools that scan through a document to analyse it. Programmers use linters to check if their code is syntactically correct and adheres to predefined code standards.
As writers we can use the same mechanism: scan our text and have the tool inform us of possible issues.
Linters are, at the most basic level, command line tools. To integrate them into Atom editor we need to first install the basic 'linter' atom package (which forms the basis of many individual linter integration packages). Once that's done we can install specific linter integration packages for the command-line linters we have installed.
$ apm install linter
Proselint (+ Atom plugin)
Proselint checks for many, many potential issues including clichés, swear words, passive voice, hyperbole, corporate speak, mixed metaphors and weasel words.
Here's the full list of proselint checks.
We need to install both proselint itself and linter-proselint, the Atom integration package:
$ pip install proselint $ apm install linter-proselint
Write-good (+ Atom plugin)
Write-good performs many of the same checks as proselint, and some that proselint doesn't. We feel they complement each other.
As with proselint, install both write-good and the Atom integration package linter-write-good:
$ npm install -g write-good $ apm install linter-write-good
Retext-mapbox-standard is a content testing tool built by the folks at Mapbox to guard against common grammar, sensitivity, and simplicity errors.
One of its features that the others don't have is ensuring your brand and jargon words are consistent: always SwiftCircle, never Swiftcircle, Swift Circle or swiftcircle.
Retext-mapbox-standard is highly configurable and understands that content might be mixed with template tags, so it's able to remove/ignore them.
There's no Atom package, but it shouldn't be too hard to build one on top of the core linter package.
$ npm install -g retext-mapbox-standard
$ retext-mapbox-standard myfile.md
Git is the most popular open source version control system today. It's used to keep track of all the changes you make to files and directories within a project, and even allows you to keep track of parallel versions of the same file(s), in case you want to try out your modifications without bothering anyone else on your team.
Though you can use git stand-alone on your machine, it's a good idea to use it in combination with a hosted service such as GitLab or GitHub. This will allow you to store all your changes and versions online as well, publicly or privately, and share them with others if you want.
In a follow-up article we'll go over the basics of git for non-developers, and how GitLab could become the centre of your editorial team's workflow.
Photo of laptop by Luca Bravo.