Stoyan Stefanov

Personal blog

 

Dear technical copyeditors,

September 8th, 2013

We need to talk.

Background

I'm a technical author. I write books about programming. I don't speak or write proper English. Not my area of expertise. I need your help. But, please, don't overdo it. Here are some Do's and Don'ts that will make our life together easier.

DON'T use Word

Stop it. I know it's not your fault but try to change this within your organization. Technical people are lucky to have discovered the beauty of source control. You know, Git, SVN, that sort of thing. Technical books should be written like programs, using plain text (asciidoc, markdown). From there you can generate epub, mobi, pdf, html whatever (lookup "pandoc"). If you're not familiar, source control is like "track changes ON" in Word, only infinitely better.

DO track your changes

Giving me a word doc changed beyond recognition with no way to quickly see your changes and no way to quickly undo what you messed up is criminal.

DO help me make my prose shorter

Delete, delete, delete! (with track changes ON, of course)

DON'T add verbiage to my prose

See above.

When I see changes like these, I want to chew my leg off and run away from the project:

ME: A number of events reshaped the web development landscape in a positive way: [list of stuff]
YOU: A number of events reshaped the web development landscape in a positive way. Some of them are given as follows: [list of stuff]

"As follows"? Search and delete all your "as follows". We can all see it follows.

ME: The cat has certain characteristics (color, name, weight) and can perform some actions (meow, sleep, hide, escape).
YOU: The cat has certain characteristics (color, name, weight, and so on) and can perform some actions (meow, sleep, hide, escape, and so on).

The golden rule: remove, do not add to the text.

DON'T remove my emphases

I use italics when I try to emphasize. This is because I can't make sense of your multiple custom formatting styles (italics, emphasis, bold, keyword, term) in your custom .dot templates. But you know your custom styles. Use the right one. Don't just remove my formatting and de-emphasize the text. It dies a boring death!

ME:
A regular expression consists of:

  • A pattern you use to match text
  • Zero or more modifiers (also called flags) that provide more instructions on how the pattern should be used

YOU:
A regular expression consists of:

  • A pattern you use to match text
  • Zero or more modifiers (also called flags) that provide more instructions on how the pattern should be used

DON't capitalize my "boolean"

Word auto-correct does it. Ditch Word. New words get special treatment initially. Then they integrate into the common language. E.g. "Web Sites" -> "web sites" -> "websites". The word "boolean" is common in programming.

ME: "numbers, strings and booleans"
YOU: "numbers, strings and Booleans"

Yuck!

DON'T just "fix" stuff

Don't reword my prose. If something's sounds off, tell me in a comment. Ask clarification. Suggest a better wording. Don't just fix it.

Otherwise we end up with nonsensical gems like:

ME:
The regular expression objects have the following properties:

  • global: [...snip...]
  • ignoreCase: Whether the match is case sensitive or not, defaults to false.
  • multiline: Search matches that may span over more than one line, 
defaults to false.

YOU:
The regular expression objects have the following properties:

  • global: [...snip...]
  • ignoreCase: When the match is case insensitive, the defaults to false.
  • multiline: Search matches that may span over more than one line default to false.

Rule #1 in technical writing: above all, be technically correct!

DO let me be human

I have some way of saying things. Many people seem to like it. Let me sound like me. Even if it's not the proper Queen's English.

ME: The function F contains the variable b
YOU: The F function contains the b variable

Err, no!

Less is more

Thank you for your understanding!

In conclusion, the top 3 tips for our happy relationship: are given as follows:

  1. Fix my punctuation, I know I suck at it
  2. Suggest lots of deletions to help make the prose compact (we all suffer from wordiness)
  3. Comment on my nonsense, don't fix

Technical writing checklist

March 5th, 2013

update: added "can", "in order to"

Working on a first draft should be quick and dirty. Then comes editing. And at the last stage, right before you're ready to send the finished manuscript, how about a checklist? A lint, if you will.

Starting the OOJS second edition I took note of my common mistakes. I came up with (and kept expanding) a checklist of last minute sanity checks that I go through before sending each chapter to the editor. Just when I think I'm ready I search for each string in the document and address potential issues.

The big picture items:

  1. Technical writing should be precise and correct above all else. Weak and ambiguous words such as "may" or "some" must go
  2. Cutting out filler words
  3. Avoiding common mistakes, e.g. "its" vs "it's"

Here's my checklist with my common mistakes. Feel free to customize for your own writing.

JSLint

Since I'm writing about JavaScript, JSLint (or JSHint) are constant companions. Consistency (semi-colons, spacing) helps the reader focus on important things. Plus, sloppiness in any form has no place in technical writing.

"very"

Filler word. Delete.

"basically"

Delete.

"actually"

Most likely not needed.

"pretty"

Doesn't help the prose, delete.

"easy"

Don't say it's easy, show and prove how easy it is.

"useful", "interesting"

Same as above. Prove it. Why is it interesting? When exactly is it useful? It's not enough to be useful just in general, because anything can be useful eventually.

"its" vs. "it's"

Common mistake. Go through and make sure it's the intended use.

"than" vs. "then"

Same thing. Search the chapter for each instance and read the sentence once again.

Shorten "it is", "you are", "you will"

This is my British publisher's issue I think. As far as I remember they changed all of these. No need. These are longer and make you sound pompous.

"way to"

Can often be removed

"we", "our"

It's all about the reader. The word is "you".

"I" can be used but sparingly. Say, 3 times in a book.

"We" sounds like "me and the crown" (this is from Packt's guidelines)

Arguments vs. parameters

Commonly mixed. It's good to be precise. Wikipedia.

function sum(a, b) {
  return a + b;
}

var price = 100, tax = 20;
sum(price, tax);

 

price and tax are arguments passed to the function sum(). And a and b are the (formal) parameters that the function sum() accepts.

"some"

Which? It's hand-wavy.

Searching for "some" also matches "sometimes", which is no good either.

"will"

(Got this from Steve Souders' reviews of calendar articles.)

Stuff is happening now. It's here and it's concrete. "will" makes it sound like it may not happen.

"The result will be..." -> "The result is..."

"may", "might"

May or may not? Weak. Ambiguous. Gone.

"probably"

Hello, technical topic here. It is or it isn't. No wiggle room.

AJAX -> Ajax

Way past the initial excitement.

"jQuery", "YUI"...

Avoiding references to current topics and events in a feeble attempt to write "evergreen" books (as if it's even possible for a computer book). Any time-sensitive info comes with "at the time of writing" disclaimer.

"can"

"Can" is weak. Doesn't mean anything. Of course you can.

"you can use" -> "you use"
"can be" -> "is"

"In order to"

Filler. Shoot at sight.

"in order to" -> "to"

Peter Thiel

June 10th, 2012

If you haven't been following Peter Thiel's lectures (transcribed by Blake Masters) I envy you. You're in for a treat. These are lectures given at Stanford and the topic is Startups, but whether or not you're looking to jump into entrepreneurship, these are fascinating reads. Heck, even if you know much about technology, you'll enjoy them.

Last night I was reading one that I skipped before as irrelevant to me (it was about giving a pitch to venture capitalists) but even if the topic is distant the content is just so good.

I don't know much about Peter, other than that he's one of the 5-6 co-founders of paypal (together with one Mr. Elon Musk who now bulids electric cars at Tesla Motors and sends stuff to space at SpaceX). Peter is also an early investor in Facebook and sits in its Board of Directors.

In these lectures Peter sometimes invites other luminaries (Paul Graham of YCombinator, Marc Andreessen) and promising startup founders from biotech, artificial intelligence and so on.

Peter makes thought provoking observations and parallels, which often have nothing to do with startups. E.g. that kings and queens are human sacrifices that figured out to prolong the time of their execution. Because scapegoats help restore piece and are worshiped before they are killed. But I don't want to ruin this for you.

Enjoy past, present and future of the human race (and startups as one example) in Peter Thiel's lectures about competition, war, distribution, secrets, luck, life, universe and everything:

  1. The Challenge of the Future
  2. Party Like it's 1999?
  3. Value Systems
  4. The Last Mover Advantage
  5. The Mechanics of Mafia
  6. Thiel's Law
  7. Follow The Money
  8. The Pitch
  9. If You Build It, Will They Come?
  10. After Web 2.0
  11. Secrets
  12. War and Peace
  13. You Are Not A Lottery Ticket
  14. Seeing Green
  15. Back to the Future
  16. Decoding Ourselves
  17. Deep Thought
  18. Founder as Victim, Founder as God

And, keep an eye on http://blakemasters.tumblr.com for the class lectures to come (I hope there's more!)

Primus

June 10th, 2012

Last night I went to see Primus at the Greek Theatre in LA and (because why the hell not) thought I should bike the 15 miles from home to the Greek Theatre. And back.

The trip was a pilgrimage of sorts. A music lover's visit to the Holy Lands of LA. Went past the unmarked grave of Frank Zappa, then bumped into a jolly gay event on Santa Monica blvd (everyone was fabulous), then Sunset boulevard with the Rainbow room (which on several Gun's Roses videos), Viper room, Whiskey a Go-Go (where The Doors took off), few chuckles by the Hustler store, the House of Blues, then Hollywood boulevard (partially closed because of yet another premiere with celebrities walking about the Chinese Theatre).

The trip length was off by a lot from what google maps says, so I missed the opening act (Fishbone), but was on time to enjoy Primus.

The show was great and the band is really really good. I've never listened to Primus carefully before I bought a ticket for the show but have listened to the last album "Green Naugahyde" a lot since. So I'm not very familiar with their old stuff, but I love the new album. One of the surprises (other than discovering how good the guitarist is and, of course, the bass player is totally nuts) was how the bassist plays this fast figure from "Eyes of the squirrel" and sings at the same time. I think humans need more than one brain for such independent tasks. Also funny was look of the audience, half of the dudes were copies of the bassist with big glasses, various facial hair styles and optional hat. Intellectual chic of sorts.

Anyway, enjoy some crappy photos, and, if you're curious, youtube has some videos of the memorable night.

20120609-215639.jpg

20120609-143633.jpg

20120609-143441.jpg

20120609-143229.jpg

20120609-215659.jpg

Beverly Hills cop

And to wrap up the rock pilgrimage experience, I had an encounter with the Law. You see I was riding the bike past midnight on Sunset Blvd in the Beverly Hills part and this police car stops me (blue-red lights flashing and all). Reason is I don't have lights on the bike. The cop starts asking me questions (I think the point was to check whether I wasn't drunk or anything) like where am I going? where's home? where was I before? where do I work? I'm currently all bearded and desperately trying to grow some of what hair I have left and overall don't look very respectable. The cop asks me to sit on the sidewalk while he's requesting a check on the radio with my drivers license. Another police car comes. So there I am, sitting on the sidewalk like a real criminal (or a naughty rock star, as I would choose to remember), two police cars partially blocking Sunset boulevard, two cops around me. Fun. It was a night to remember.

As it turns out I don't have a police record, all is fine, we separate on great terms and I'm thinking: man, I should've asked to cop with the bigger car give me ride home because this bike was a little too much.

AsciiDoc

June 8th, 2012

When in phase #2 of any writing process (the typing phase) you need minimal distractions. You need to just type away as frictionlessly as possible and lose no time at all in anything other than typing.

That's why MS Word (or any word processor really) is poorly suited for real typing, as oddly as this sounds. There's just too much UI going on, menus, options, toolbars. Even if you ignore and manage to hide these, it will causes damage with auto-correct and smart quotes in your code examples and so on. You don't need any of that. You don't even need to see that there's an option to make something bold or italics. Because that will make you think. Should I make this bold? Or maybe italics? All this takes your energy and causes you to type less.

Word is also terrible for writing code. It's simply not a code editor.

The best software for writing a computer book is simply your favorite code editor. It has everything you need, and everything you're used to. Tabs vs. 2 or 4 spaces and so on. Auto-complete. Your favorite macros and shortcuts that you normally use every day.

Your book is best written as plain text, as close to normal source code as possible.

Plain text

When I started typing away on JS4PHP, I just used TextMate which is what I use for coding anyway. I just wrote text. I thought of writing HTML initially and then use something to convert it but quickly reconsidered. Typing <code>var a = 1;</code> is too much typing. Opening and closing tags - meh.

The cool part about TextMate is that that is has auto-complete based on what you've typed already. So I got accustomed to write Ja, hit ESC and watch it complete to JavaScript

Knowing that there will be editing I figured the sloppier the original, the more rigorous the editing, so I just didn't bother to format almost at all. I couldn't help myself putting some ` though as in Here the function `foo()` is .... when dealing with code inline if a paragraph. Or some *really* and this is called a _closure_. You know, little markup pieces.

Once the first ugly draft was done, I started looking at how to convert this plaintext into something O'Reilly can use. I have heard of something called docbook or bookxml or something similar and suspected that O'Reilly supports it. So I though I have to take my plaintext and make it XML. But much to my surprise I learned that O'Reilly supports AsciiDoc.

AsciiDoc

AsciiDoc is an open source project that lets you write plain text with minimal markup and then generate a bunch of different outputs from the source.

For example `inline code` and *bold* and _italics_ and then some highlighted source code:

[source,js]
----------------------------------------------------------------------
// JS
var a = 1;
----------------------------------------------------------------------

[source,php]
----------------------------------------------------------------------
// php
$a = 1;
----------------------------------------------------------------------

Of course the [source] parts you add later, at editing time. While typing you just type the code.

Macros

Writing in your favorite code editor lets you come up with all kinds of macros and shortcuts.

Think about writing code MS Word. It's a pain. You write code and word mangles your "s and your 's. You undo. Copy the code, execute it somehow in a different program and/or terminal. See it has a syntax error. Fix it. Copy back to word. Then later decide to rename `foo` to something more informative. Repeat or risk publishing broken code.

In a code editor it's much easier, you write code in its natural environment. Then you can probably think of something to execute the code.

For me writing about JS and PHP it was two simple TextMate commands to run the code.

JavaScript:

#!/bin/bash
echo "$TM_SELECTED_TEXT" > ____.js
echo "<pre>"
echo `/usr/local/bin/node ____.js`

And PHP:

#!/bin/bash
php -r "{$TM_SELECTED_TEXT}"

I assigned shortcuts to these and then everytime I write some code in the book, I select it, press the shortcut and observe the result. Really quick feedback loop to fixing any errors.

In fact I have another JS TextMate command:

console.log('code: $TM_SELECTED_TEXT, result: ', $TM_SELECTED_TEXT);

Which makes it easier to spit out results.

Refactoring whole chapters and the whole book is also trivial when you deal with plain text (source code) in a source code editor.

Type all the things!

Removing friction out of typing is an enormous help. And writing a book in your favorite text editor and using something like AsciiDoc or markdown makes the process so much easier.

Another cool thing about O'Reilly specifically is that they give you an SVN repository where you check in your .asc files and images. Then they have a commit hook that generates a very production-like PDF (it's really asciidoc -> the weird book xml -> PDF) every time you commit changes, so you can see your creation formatted with all the O'Reilly styles, just like the real thing (barring some oddly positioned images, because of the autogeneration). The whole thing is not as immediate as edit-save-refresh web programming (it's edit-commit-wait-twitter-`svn up`-open PDF) but much better than the usual edit in Word -> send to Editor -> wait a month -> see the result

Writing vs. typing

June 7th, 2012

Many people find the idea of writing a book or an article difficult. I think this is mainly due to a poor definition of what writing is.

In the movies, there is this romantic idea of the process. The author struggles, drama ensues. Then all of a sudden inspiration strikes. The author sits down all night just listening to what inspiration says and lo!, in the morning among a pile of cigarette butts and empty wine bottles, there is a brand new spanking chef-d'œuvre of a manuscript. Everyone who reads it says it's the best thing ever! Or, if the author is ahead of his time, as often happens in drama, at least those who know anything about anything and are not as dumb as the average Joe, love the thing. The author is done. Let's celebrate, while waiting for the next visit by her majesty, the Muse.

That's definitely not how it works with computer books. I don't have first-hand experience with fiction, but from what I've read from fiction writers, that's not how it works with fiction either.

When people buy into the romantic idea of the Muse and one-off writing sessions, and they try to write, no wonder they fail. Imagine out hero saying "heck! I'm going to write a book!". He creates a new folder, a new file called book.doc and proceeds typing the title: "Responsive Design with HTML5 and CSS3". He likes it. Next, a subtitle. "Unleash the power of mobile, social, local, yadda, yadda.". OK, so how big should the title be? What about the subtitle? 20 mins struggling with formatting options in Word. The future author goes: meh, I'll worry about formatting later. New page.

White page...

Big white page...

"History of HTML? Boring."

White page...

"Should I open with a joke? But what if it falls flat?".

White page.

Open the browser. Search "writer's block". Tweet about your writer's block... #fail

You see how the prospect of writing is scary for many people.

So what can you do about it?

Divide and conquer

You can split the process of writing in three phases.

  • Thinking: what am I going to say?
  • Typing
  • Editing: making what you typed readable

step #1: thinking

Most often people don't think about #1 as writing, But it is. It happens when you walk, bike, do the dishes, and most often in the shower. That's why the aspiring author should make time for those mindless activities.

There is a clear deliverable from this process: the TOC (table of contents). Bullet points of what you want to say. Probably split into chapters, although not until later in the process. The first part is just a list. A todo. You can use paper and pen. Or type in your phone if you don't have paper handy (you're on a walk). This is not as intimidating as the big bad Writing, because the outcome is 2-3 pages. Although the more, the better, because it means you have a detailed todo and don't leave much to think about in the next phase.

You can also take this TOC and do a slideshow. Give a presentation in a local meetup or your workplace. This is a nice checkpoint. If you're not confident people will be willing to listen to a talk, what makes you thing people will be willing to read a book about this topic. Each slide heading is a minor subtopic, a thought. Any words or code one the slides are the key points in the thought. When it comes to step #2, you can just copy-paste the slide and clarify the code or the key points.

step #2: typing

This is what people often refer to as writing and are scared of. But it's not writing. It's just typing. Mindless, easy typing. Anyone can do it.

You paste the TOC (or the slide content) and fill in the blanks. Add more explanation about what what you means with this item in your list.

It's very important that you don't read or edit at this stage. No formatting. No editing. No reading. Just typing away, filling the blanks. Just like filling our a form.

Like an email. Most people are OK with writing emails. They don't consider this writing. There's no writer's block. Someone asks you a question, you reply and type away. An email has a subject. What you're writing about has a subject (one of the TOC items). It's just like answering a question.

Next TOC item.

Next.

Before you know it, you've typed quite a bit. Resist the temptation to do editing. Keep typing.

I found it really helpful to set up time first thing in the morning and type for an hour or half an hour. It's awesome. It's the morning and you already have something done. Something is accomplished. Words are down on paper (of course you haven't read the words and you have no idea how bad the writing is, and this is a good thing). You feel good the rest of the day. Even if the rest of the day is just busywork and fixing urgent bugs or sitting in meetings or sitting in traffic, you have your morning, you have been productive already. In the night you may write more or you may not. You may enjoy going out or just being lazy.

So think of this stage as just typing which is easy and brainless.

step #3: editing

This is a read-write loop: you read what you wrote and you fix it. You move stuff around. You add, you remove, you refactor. Then you do it again.

You may be surprised initially that the stuff what you wrote in step #2 looks like, let me quote Frank Zappa here, some of the most terriblest shit you've ever known. But it's fixable. It's down on paper. Writing's done, you have pages and pages of text. You're an author! The rest is editing. And you can do it anywhere.

The typing is the only part that requires you to sit down in front of a screen. Thinking/TOC is done outside the four walls. I do most of my editing outside too. By the pool, the beach, even walking. I can do it in while in line at the store. You just print what you wrote and scribble on top of it.

I suggest the first edit is on the computer though because there will be too much scratching.

You can do the formatting in this stage. And print and edit. For some reason it's easier to spot mistakes in printed words. If you're into grammar checks you can also read backwards. For me, English is not my language, so I don't even try to fix grammar. That's you have an editor. If you don't have a publisher, I hear you can hire an editor.

Then there's the technical review, which is also critical. You try to find the best people on the topic to agree to read your stuff and point your mistakes. Because mistakes you will make. Fact of life, no matter how smart you are. So then another round of editing. Then the grammar Nazi kicks in and fixes your commas. And another round of editing.

All in all you'll spend more time editing than typing. Editing takes time. That's why you keep it off the typing phase. It takes time but it's not writing. Again, no writer's block here. You can do it outside in the Nature.

Misc

A few more random thoughts on the typing phase.

Douglas Crockford said in a talk that if you take all the code you've written in a year and just retype it, it will take only a day or two. Three. A week. Long, unpleasant days. But just days. So what are you doing the rest of the year. Definitely not typing.

The typing is to writing what a hackathon is to software engineering. The outcome is a hack. It's ugly but it works. It exists where it didn't exist yesterday. You've created something. It's relatively quick. Then you have to go back and make it right and solid and properly engineered.

Coding and writing technical books have similarities, but there's one difference: you can run the code and see if it does what it's supposed to do. With a book there are many right answers and outcomes that work. You just have to do enough of it to discover your opinion and feel for what works. The book is like source code that doesn't print anything out. So you're working to make the source code of the book readable and maintainable.

The blog hack

Forgot one more thing: blogging is a nice way to hack writing. You don't need a whole TOC, just one item. Then you type. Then you hit "publish". (ok, maybe read it once first, but then publish immediately). Then you edit if you want. No need to do much editing though. You have a feedback loop from the readers, if people point out mistakes in your logic, code, writing or whatever, it doesn't matter how polished and grammatically correct it is. You can edit the technical part first which is the most important. A technical book should first and foremost be technically correct.

Repeat the blog hack enough times on related subjects and voila, you have a book. You only need to tighten it up and do more editing.

Go!

Now go back to work! Stop writing and start typing already!

wordiness

August 27th, 2011

Started (again, but this time immagonnafinish!) working on OOJS second edition. I'm finding some wordiness I'm gladly deleting.

"pretty" isn't

"Pretty" is just as bad as "very". And here's what Mark Twain has to say on "very":

Substitute damn every time you're inclined to write very; your editor will delete it and the writing will be just as it should be.

I had "pretty soon". That's just "soon".

I also had "pretty good". It can simply become "good", but I thought better yet why not try to find a more descriptive word. I had written that learning JavaScript is "a pretty good deal" because you learn one language and you can program for many different environments (shell scripting, mobile, etc). At the end I decided "smart investment" is much better than "pretty good deal".

more often than not

That's just plain "often".

-oriented

March 25th, 2010

From The Elements of Style's chapter on Misused Words and Expressions:

-oriented. A clumsy, pretentious device, much in vogue. Find a better way of indicating orientation or alignment or direction.

They suggest instead of

It was a manufacturing-oriented company.
Many of the skits are situation-oriented.

it's better to say:

It was a company chiefly concerned with manufacturing.
Many of the skits rely on the situation.

So for the second edition of "Object-Oriented JavaScript" should I suggest to the publisher the title "JavaScript chiefly concerned with objects" or "JavaScript that mainly relies on objects" or maybe "Programming with the JavaScript Language while Mainly Concerned with the Use, Nurture and Care of Objects":)

Django’s stairway

February 12th, 2010


I'm a fan of Django Reinhardt since.... a few weeks ago. See if you can hear his influence in the two short pieces below - they are sort of gypsy/jazzy, yet warm and fender-y, parts of Stairway to heaven. The second part if the Am-G-F solo at the end.

Django's Stairway
Django's Stairway 2

Jimi yodel

October 14th, 2009

So Yahoo! is in the middle of a brand campaign. There's a whole Yodel studio, three actually, in NY, London and Mumbai, where people go and yodel with different background music. You can do too, online. The site even offers the downloadable background tracks for your mixing pleasure.

I couldn't just sit and watch, now could I? After all, I've helped the Yahoo brand before, why stop now. So I took the Blues background from here (the separate zipped tracks are here), dusted off the old axe and, too embarrassed to yodel vocally, did so with my wah-wah, in what I was hoping would resemble Jimi Hendrix style.

Here's the really short result piece, enjoy.
Jimi yodel

Powered by WordPress, theme by ♣w3clubs.com, based on Kubrik and Sancta Simplicitas