Write like a human, not a robot
Use a conversational tone when writing content for people
Bruce originally shared this as a LinkedIn post, and was kind enough to give us permission to re-share it as a brief article on Technically We Write:
Do not ever write in the oblique mode, or use passive voice, even if certain people, and worse, technical journals, insist that you do so. Push back or publish with smarter venues.
Here's an example of what I mean: The first paragraph is in oblique mode, the second explains the exact same topic in conversational mode.
Oblique mode:
The translation of human-readable alphanumeric resource locators into routable Internet Protocol identifiers is effectuated through a decentralized, hierarchical nomenclature system. When a query is initiated at the application layer, a localized resolver mechanism queries root zone directories, proceeding iteratively through top-level and authoritative namespaces until the mapping resolution is ascertained and subsequently cached. Consequently, infrastructural connection protocols can be instantiated between the client origin and the destination host server without the requisite memorization of arbitrary numeric matrices by the end user.
Conversational mode:
Think of the Domain Name System (DNS) as the internet's phonebook. When you type a website name into your browser, your computer doesn't actually know how to find it because computers navigate using numbers, called IP addresses. DNS translates that easy-to-remember name into the exact string of numbers your computer needs to connect to the site. Behind the scenes, it quickly asks a series of directories for the right number, links you to the website, and saves the number for next time—saving you from having to memorize long lists of digits just to browse the web.
This is an excellent reminder that we should always keep our reader in mind when we write. People can more easily understand direct, action-oriented language. Review what you write to make sure that you avoid passive or "oblique" voice when writing documents. Use parallels to draw examples, and write in plain language.
Thanks to Bruce for sharing this article with us.
Bruce Perens is a well-known open source advocate. Bruce wrote the original guidelines that were later adopted as the foundation of the Open Source Definition.
