Writing

The Boy Who Cried Wolf

By Evan — — Personal, Writing

This is the story as we have always told it, for over two thousand years. Not a word has been changed.

There once was a village that decided to task a young boy with guarding his village’s sheep. It was a crushingly boring task. The sheep essentially minded themselves, and as the day wore on, the child became desperate for attention.

Finally, the boy called out, “Wolf! A wolf is coming!” The grownups of the village tore themselves away from their important work and came running to drive the wolf away. But when they got there, there was no wolf.

The grownups grumbled at the boy. One of the village elders said, “This is a very serious responsibility! Don’t ever call out ‘Wolf!’ unless there really is a wolf.” The boy broke down in tears, apologized and promised to do better.

On the second day, the boy was again crushingly bored. The day wore on, and eventually, despite his promise, he called out, “Wolf! A real wolf is here this time!” Once again, the grownups came running. And once again, they were frustrated at the boy’s irresponsibility. The village elder thundered at the boy, “How dare you! You have broken your sacred trust again!” The boy broke down in tears, and made even more promises.

Nevertheless, on the third day, the grownups of the village chose to put the boy in charge of the sheep again. And when the boy cried out for help, they decided not to come.

Writing for Developers: Characters and Action

By Evan — — HOWTO, Technical Writing, Writing

In the previous post in this series, we discussed nominalizations (verbs that have been transformed into abstract nouns), and how converting abstract nouns into concrete verbs can improve your prose. In this post, we’ll get a little deeper into why that is.

English sentence structure follows the form subject-verb-object (abbreviated SVO). In the sentence,

Amanda optimized the code.

“Amanda” is the subject, “optimized” is the verb, and “the code” is the object. Here we know that Amanda is the one doing the optimization, thanks to the sentence’s SVO structure and its context (it doesn’t make much sense for the code to be optimizing Amanda). If we pick a more ambiguous sentence,

Joanie murdered Chachi.

then the only thing we have to go on is SVO.

This brings us to characters and action. Even in highly abstract, technical prose, we tend to understand sentences in terms of characters (agents) who are performing actions. When a sentence hides the characters, or misdirects our attention onto the wrong characters, or obscures the main actions of the characters, the sentence becomes harder to read.

The good news is that all languages, including English, provide a basic structure that you can leverage to communicate these concepts. A sentence is clearer when the subject corresponds to the characters, and when the verb corresponds to the major actions of those characters.

Let’s start messing with our example sentence. To start with, Amanda doesn’t have to be the subject. We could write it this way,

The code was optimized by Amanda.

Now the code is the subject and Amanda is the object. Semantically, we know that Amanda is the “actor” or “agent”, and the code is the “goal” or “the thing receiving the action.”

“Amanda optimized the code,” is an example of an active sentence, where the subject is the character, and the object is the goal of the action. “The code was optimized by Amanda,” reverses this relationship: the goal is the subject and the character is the object. This is an example of a passive sentence, where the subject expresses the goal of the action.

As is often the case, the passive sentence is slightly worse than the active sentence. It’s a bit more wordy, and we have to do a bit more work to figure out who the character is. But we can make it a lot worse by using the powerful tool we learned about in the previous article, the nominalization, to mess with the action. Let’s turn the verb “optimize” into an abstract noun:

The optimization of the code was performed by Amanda.

Now that “optimization of the code” is the subject, the reader has to unpack the sentence even more carefully: they need to mentally discard the empty verb “performed,” and realize that the action is actually something else.

Alternatively, we can make our character Amanda disappear entirely, by removing the by-clause:

The code was optimized.

Perfect for avoiding giving credit, or diffusing blame!

Before closing, I want to be clear about two things. First, there are many ways to write bad prose that have nothing to do with passives. Second, passive sentences are a tool, and they exist in the language for a reason. In a subsequent post, I’ll provide some examples of using passive sentences for good, not evil. Until next time!

Writing for Developers: Nominalizations and You

By Evan — — HOWTO, Technical Writing, Writing

Any engineer worth their salt knows that writing is a big part of the job. But for many of us, that can be a scary prospect. Some of us haven’t had a lot of formal training in writing, or English isn’t our native language — or both. We’re supposed to “write clearly,” but nobody ever explains how exactly to do that.

So I thought I would share one of my favorite low-level writing techniques. It’s widely applicable, and it’s doable as long as you are able to identify core parts of English (nouns, verbs, and adjectives). The technique is: find and eliminate nominalizations.

What is a Nominalization?

A nominalization is an abstract noun derived from a verb or adjective. For example:

  • initialize, the verb, becomes initialization, the abstract noun
  • minify, the verb, becomes minification, the abstract noun
  • elegant, the adjective, becomes elegance, the abstract noun

Side note: some nominalizations have the same form whether they’re an abstract noun or a verb. English is weird like that.

Aside from the occasional edge case (beyond the scope of this post), it’s usually an easy win to scan your draft for nominalizations and replace your abstract nouns with verbs and adjectives. Let’s see how this works in practice.

Example of Eliminating Nominalizations

Here’s an example of a very bad sentence (written by me, on purpose):

The Security Council’s proposal would provide for individual engineering team certification of the resilience of any new applications that were requested for exemption from core network security guidelines.

Here I have used all my dark powers to write an unclear, but still syntactically correct English sentence. Before continuing, please re-read this sentence as many times as you need to in order to understand what it’s saying.

How do we fix this mess? Let’s start by flagging the abstract nouns:

The Security Council’s proposal would provide for individual engineering team certification of the resilience of any new applications that were requested for exemption from core network security guidelines.

The equivalent concrete verbs and adjectives are:

  • proposal (noun) / propose (verb)
  • certification (noun) / certify (verb)
  • resilience (noun) / resilient (adjective)
  • exemption (noun) / exempt (verb)

Breaking into pieces and replacing the nominalizations looks like:

  • “The Security Council’s proposal” can become “The Security Council proposes”
  • “team certification of” can become “team certifies” or “team must certify”
  • “resilience of any new applications” can become “new applications are resilient”
  • “requested for exemption” can become “request [them/us/the council] to exempt” or even “ask […] to exempt”

Stitching the pieces back together:

The Security Council proposes that when individual engineering teams ask us to exempt new applications from core network security guidelines, the team must certify that the application is resilient.

This new sentence isn’t necessarily great, but we’ve at least managed to unscramble it. This is in spite of the fact that we haven’t radically shortened the sentence or done any deep surgery. The sentence still says what it said before, with mostly similar word choices. All we’ve done so far is convert four nominalizations (and if we’re being scrupulously honest, we’ve added a fifth verb, “ask”).

So why is the sentence easier to read? It’s because converting abstract nouns to verbs and adjectives has forced us to clarify who is doing what.

More generally, “clarifying who is doing what” is one of the more powerful tools you have available for improving your prose. This is often what readers actually mean when they complain, “This is unclear.” When a reader says this, a probable root cause is that the sentence hasn’t properly identified its characters and their actions. In the next post, I’ll dive into this in more detail.

Template for Making Ebooks with Pandoc Markdown

By Evan — — Writing

After reading Charles Stross’s article, “Why Microsoft Word Must Die“, the thought occurred that someone, somewhere might be interested in using Pandoc Markdown for generating ebooks.

If you’re writing fiction, Pandoc is probably too nerdy to bother with. You should use Scrivener, which is highly polished and produces fine ebook output with the press of a button. However, if you like to work with a manuscript as a collection of plain text files that you can check into version control, Pandoc fits the bill nicely. It’s a bit easier to understand than Sphinx, and it can handle anything up to moderately complex technical books.

So in case anyone finds it useful, here’s a project you can use to get started: https://github.com/evangoer/pandoc-ebook-template. Pull requests welcome!

Software Backup for Writers

By Evan — — Writing

[Cross-posted to the Viable Paradise blog.]

The oldest known printed paper book was published in China well over a thousand years ago. The oldest fragments of Egyptian papyrus have survived over four thousand years.

The lifespan of a manuscript on a hard drive: about five years. A hard disk drive consists of platters that spin at thousands of RPM. Inevitably, these mechanical parts will fail. A solid state drive lacks mechanical parts, but due to unfortunate quantum mechanical effects, it can only record a limited number of writes. As with the hard disk drive, the more you use your solid state drive, the sooner it will degrade and die.

HOWTO fight Entropy (or lose more gracefully)

At a minimum, you should make sure that your work resides on:

  • At least two drives you can access locally
  • At least one drive in an offsite location

Here are a few strategies you can use.

Buy a external hard drive

There’s a good chance your computer only has one drive, particularly if it’s a laptop. The easiest way to rectify this is to buy an external hard drive. Even if funds are tight, please at least consider investing in a second hard drive, as the data on your computer is probably much more valuable than the hardware.

In a pinch, you can use a small USB drive. USB drives are inexpensive (often free, if you’ve mastered the art of lurking around corporate conventions), and they’re usually big enough to store all your documents.

Once you have an external hard drive, you’ll need some software to perform automated backups. Mac OS X systems have a built-in service called Time Machine, and Windows 8 has a similar service called File History. Windows 7 has a simpler backup system called Windows Backup. There are also a plethora of third-party backup software to choose from. Just make sure you have at least some automated system chugging away. Don’t rely on manually dragging your files over to your external drive. You won’t remember to do it.

Set up a network attached storage device

This is the geekier version of buying an external hard drive. A storage device is a fine option if you enjoy tinkering with hardware and software, or if you know someone else who does. Get some friends together and have a FreeNAS build party! Serve pizza! It’ll be awesome.

Alternatively, you can invest in an proprietary storage appliance such as a Drobo. They are very shiny.

Use a cloud service

Google, Zoho, Microsoft, and various smaller independent companies and startups offer online writing tools that store your documents in professionally run data centers. There your documents will be preserved, nearly impossible for anyone to destroy (even if you yourself do your best to try). Many other companies such as Dropbox, Box, Crashplan, and Tarsnap don’t provide authoring tools directly, but enable you to sync and preserve files in general.

The advantage of cloud services is that they handle backup in a sort of Platonic ideal way, without requiring conscious intervention on your part. The disadvantage of cloud services is that the companies that provide them either tend to get bored with their current strategy and/or go out of business. So if you do choose to use a cloud service, be sure to regularly export the documents you care about to some common, popular format and save them on your local systems. For best results, stick with companies that appear to have sustainable business models, and avoid the ones that are just moonlighting or that are in the process of being prepped for sale by their VCs. Further reading: Maciej Cegłowski’s Don’t Be a Free User, Jason Scott’s F**K THE CLOUD (NSFW language).

Use remote version control

The simplest and most common form of version control is to litter your hard drive with files named things like, “My Story 20-Dec-2014.doc”. (It’s okay if you do this. We’re not judging.) A more elegant solution is to use Windows File History or Mac OS X Time Machine. These tools enable you to “go back in time” and restore a file to a previous state.

If you’re not a huge software nerd, this is a fine place to stop.

However, if you are a huge software nerd (or at least a hobbyist), you might consider using a true version control system such as Git or Subversion. Not only do version control systems provide you lots of powerful features, but they also enable you to sync your manuscripts to remote repositories such as GitHub or BitBucket. BitBucket offers private repos for free, which makes it an appealing choice for authors.

Note that version control systems are not the best place to store binary formats such as Word docs. If you’re going so far as to use Git, consider going even even nerdier and writing your books in a plaintext format such as LaTeX, Pandoc Markdown, MultiMarkdown, or reStructuredText.

Take a page (ahem) from our Egyptian and Chinese ancestors

Print your final manuscript out on paper. This is a great way to ensure that at least some version of your work will survive a catastrophe — and will likely even be readable decades from now, when all the software we use today is long, long dead.

If all else fails

Perhaps you ignored all the options above, and your only hard drive failed. Or perhaps you backed up your documents all over the place, and the universe just hates you. The good news is, there are companies that specialize in salvaging data from failed and damaged hard drives. The bad news is, using a data recovery service is a lot like casting Raise Dead: it might not work, and it’ll cost you most of your gold.

Remember: any strategy is better than no strategy

This has just been a short overview of a few possible options. There are many more to think about, and it’s up to you to assemble them into a system that makes sense for you.

Admittedly, it’s hard to get religion about backups if you haven’t been bitten yet. In fact, there’s a good chance your lizard brain is telling you, “Well this backup thing doesn’t sound that scary, and hey, by the way, we’re hungry, doesn’t a snack sound nice right around now?” Ignore your lizard brain! Do something!

In the interest of full disclosure, I’ll admit that I’m not perfectly happy with my backup strategy either. For the record, my strategy these days is: Time Machine to a storage device, plus a remote Git server and DropBox for offsite backup of certain critical projects. That has me covered for some situations. I could be doing a lot more.

What’s your backup strategy? What are you going to do in the next week to make your strategy better, even if just by a little?

What To Do About Language Bullies

By Evan — — Writing

I enjoyed this Slate article, Are You a Language Bully? a great deal. The one thing I’d add to it is that most of the things that language bullies like to harp about are actually incorrect when you bother to do a little research. Take the example from the article where an NPR listener complained about using “decimate” to mean “destroying a large portion of” rather than, “executing every tenth person.” A quick survey of no less than four dictionaries reveals
that every single one of them lists “destroying a large portion of” as a definition, and three out of four list it as the primary definition.

If you’re faced with a language bully, do a quick search through a dictionary or through Language Log, and there’s an excellent chance they’ll have the goods on whatever your bully is complaining about. Your language bully is operating based on whatever feels right to them; the professional linguists who run Language Log enjoy writing Python scripts to crunch through reams of English text in their copious free time.

The other thing about language bullies is that like most bullies, they learned their behavior by being bullied themselves. It might feel good to “punch the bully in the nose” with your answer, but instead, please try to be kind and respectful. With proper guidance, language bullies can be reformed! Believe me, I know.

How the Random House / Hydra Contract Becomes the New Normal (For a While)

By Evan — — Writing

John Scalzi has the goods on Random House’s new Hydra vanity press, and the contract really does sound awful.

If you want to publish fiction, there are two main options.

  • Go with a reputable publisher. Advantage: the publisher fronts a bunch of fixed costs around book production and distribution and pays you an advance. Disadvantage: your book might never be published, and the publisher keeps most of the revenue from your book.
  • Self-publish. Advantage: You keep the lion’s share of the revenue. Disadvantage: you get no advance, and you have to front the cost of design, editing, art, etc. (Though if you don’t give a rip about design, editing, art, etc., this cost could be close to zero.)

Random House / Hydra combines the worst aspects of both paths. Unlike going with a publisher, you get no advance, and you end up paying the fixed costs of production. Unlike self-publishing, you only get 50% of the revenue, not 70% or 90% or 97.1%. And critically, unlike either of the above options, you lose your rights over your own work, in perpetuity. Random House assumes no risk and takes 50% of your money — forever. Just unbelievably cynical and awful.

The trick will be making this kind of contract the new normal. Here’s the playbook:

  1. Full court press in industry publications and social media, arguing that the contract is actually fantastic for authors, 50% is like totally way better than 15% you guys duh, and anyone who says otherwise is a fuddy-duddy who doesn’t get The Internet and hates puppies.
  2. Select a handful of authors and spend serious money promoting them, making sure they rack up some respectable sales by hook or by crook. Brag a lot about the top-line numbers.
  3. Wait for shit-rags like Business Insider and Newsweek and Slate to dutifully churn out praise for this brave new business model. Wait for this sentiment to work its way up the media food chain.
  4. Profit???

I dunno. The thing is… if I worked for Random House, and if I were worried about competing with Amazon, Apple, Smashwords etc., I would spend some time thinking about how I could offer a better deal. I’d at least try to match their terms, and maybe add some unique features that the others can’t match. The last thing I would want to do is construct a business that is worse than what my competitors currently offer in every respect, and that promises razor-thin margins for a few more years at best.

It seems like an awfully ugly way to die.

The YUI 3 Cookbook Draft is Done

By Evan — — Writing

For certain values of “done.”

  • Quite honestly, it still could use a couple of Loader recipes.
  • And at least one more i18n recipe.
  • Not to mention Luke Smith totally stole my tripleclick synthetic event recipe and did it better, so I need to redo that one from scratch.
  • Plus I need to update the App Framework recipes for 3.5.0.
  • Ditto for most of the Node.js recipes.
  • Above all, I should really give it a global editing pass before it gets to the editor and copy editor.

Yes, but aside from Loader, i18n, synthetic events, the App Framework, Node.js, and a global editing pass, the draft is done!

  • Maybe a FocusManager recipe.

In the Grim Darkness of the Far Future, there is only Word

By Evan — — Writing

At least, for writers trying to submit electronically to markets. Micah explains the problem.

For markets that take paper submissions, submitting in Standard Manuscript Format is not a big deal. You can use whatever wacky production process you like and print the thing out. Done. Heck, I even wrote an extension to Sphinx to produce sffms-latex from reStructuredText. It even works! Mostly.

But as time goes on, this “analog hole” will go away. As electronic Standard Manuscript Format becomes the defacto format, all of us crazy hippies really will be forced to use Word. For reals. Or possibly Scrivener, which does a pretty good job of exporting to Word. Actually, come to think of it, that doesn’t sound too grim-dark, does it? Although I do have it on good authority that Scrivener creator Keith Blount sustains his decaying body by sitting on a great cybernetic throne and draining the life-energy of a thousand psychics every day. So there’s that.