Editing codes are heaps cool and here I indulge some flights of fancy about their future.
Nowadays, technical writers are meeting developers where they are (docs-as-code anyone?). At the same time, developer advocates and dev-rellers are doing more tech writing.
As a result, we’ve got lots and lots of prose stored where code lives: GitHub, GitLab, Radicle, etc. That has resulted in the behavior (or sensibility?) of applying things to prose that were intended for code.
I think that editing codes are a tool that can bring value to this intersection.
Conventions
For code, Conventional Commits is a way for people to add meaningful commit messages. Is it a fix? Is it a breaking change? This lightweight convention adds structure and flags intent, making it easy for humans and machines to understand.
The same idea, for prose, is Conventional Comments. This system gets shared a lot amongst tech writers who are reviewing writing in a source control system like GitHub.
“Comments that are easy to rock and grip”. (I think they really nailed the tagline.)
This convention is easy to share, and quick to pick up. After you’ve scrolled the page you’re ready to start using the system.
…with room for improvement
The Conventional Comments system is a step in the right direction for reviewers to apply some rigor and meaning to their feedback.
What I have found in practice, though, is that this system lacks nuance for reviewing technical writing.
- Some things that are small aren’t nitpicks.
- Almost all edits are suggestions, so the
suggestionlabel isn’t meaningful.
Here is an opportunity for editing codes to supply a useful level of granularity.
Prose linting
Another popular tool for working with prose in a docs-as-code workflow are prose linters. Vale is one of the most popular. It’s a command line tool that applies your editorial style guide to your writing - but you can hook it up to other style guides like Google or Microsoft.
A lot of the rules are for punctuation and grammar, but there are accessibility extensions that look at the use of inclusive language.
I’m excited about the idea of plugging the editing codes into Vale.
Your idea here
Interested in working with OSP to bring editing codes to your workflow? Check them out and get in touch.
Disclaimer: I use editing codes everyday, so I may be blinded by enthusiasm.
Image credit: Stormtrooper photo by Photo by Daniel K Cheung on Unsplash
