From 416 to 905 ...

Books cannot be killed by fire. - FDR

via ebooktest.files.wordpress.com

I forgot about this recently. Now I remember. Thanks, Mike Cane!

Tuesday, December 29, 2009

Blog: What do I delegate, and why? » sacha chua

Setting appointments: Great. They follow up with people and manage my calendar. People’s reactions are fun, too.

Following step-by-step routines: Good. Because the task is done by any available assistant, I sometimes benefit from different perspectives, and sometimes get people who overlook a step. I’ve given my routines one-word shortcuts so that I can e-mail complex requests easily.

Comparison shopping: Okay. It’s a good idea to specify which stores you want, and even better if you can specify the item you’re looking for. I’m in Canada, so I need to remind them to check if retailers will ship to Canada and to factor in shipping costs when comparing price.

Web research: Hit or miss, unless the search is very specific. Maybe it’s the 15- to 30-minute “task window” they work with, or differences in approach, or even English skills. Still, it’s a decent way to get started on a task, and even wrong results teach me more about what I’m really looking for.

Calling for information: Good. I don’t have Web access on my phone, so if I’m out and I need to confirm information that’s not on my iPod, I can call them. It’s a US call, though, so I ask them to call me back with the results. The turn-around time is decent.

via sachachua.com

I have been pondering about Virtual Assistants as well.

I consider this a MUST READ

Superpowers at work.

I can sit at one of those meetings where the customer is annoyingly vague about his requirements and keeps waving his hands around as if it explains anything. I ask few questions, drilling down into specific requests he’s made and after the meeting, I tell my team: “The customer wants X. He forgot to ask for Y, but he’ll need this too. He’ll be very happy if we’ll throw in Z as well. He doesn’t need W, even though he asked for it, so we can skip it.”. I always get this right.

via prodlife.wordpress.com

Saturday, December 26, 2009

Mission Accomplished! Boxing Day Sale Win at Future Shop!

Just bought a new netbook at Future Shop.
As you can see, they only had ten at the cheaper price. I bought the ninth.

Here is to waking up at 6AM.

Thursday, December 24, 2009

Beautiful Losers: @mikecane is right, The Author's Guild are dumbasses.

It would therefore have been deeply satisfying, on many levels, to litigate our case to the end and win, enjoining Google from scanning books and forcing it to destroy the scans it had made. It also would have been irresponsible, once a path to a satisfactory settlement became available.
Litigation, particularly litigation over the bounds of fair use, involves risk. Some critics of the settlement wrongly dismiss that risk, but the fact is that we certainly could have lost the case. Losing would have meant that anyone, not just Google, could have digitized copyright protected books and made them available through search engines. Since creating a search engine is rather simple, anyone with a website -- Civil War buffs, science fiction fans, medical information providers -- would then have been empowered to start the uncontrolled scanning of books and the display of "snippets." Authors would have no say in those uses and no control over the security of those scans. The damage to copyright protection would have been incalculable.

via authorsguild.org

The Authors Guild - Ursula K. Le Guin, Google, and the Economics of Authorship

This letter is wrong on so many levels.

1) Why would it be good if Google destroyed all the scans they have already done?
2) As per Mike Cane, these people are dumb. It is not easy to create search engines. If it was easy, Google won't have a monopoly on search engines.
3) Display of snippets is still not display of the book. I don't know if these guys know about a place where they are giving out the entire content of the book for FREE. It's called the library.

Personally, I don't think these guys knew what they were doing. One of the interesting that came out of the original settlement was that it gave Google a de facto, legal monopoly over all digital books. I guess this new settlement only gives Google an effective monopoly, as no other entity would spend the billions to scan all the out-of-print books.

So, new stream of income, Yes. But it would be only from Google, set by Google (with the occasional prodding from the Author's Guild to try to increase it.) It's not like any entity will emerge any time soon to challenge Google at this.

Wednesday, December 23, 2009

There is nothing sexy about Dostoevsky

Underground Man is sexier than Pierre Buzukhov

via laurenleto.wordpress.com

This is stupid, try-hard crap.

Quote: Book publishers are idiots

One key advantage of corporate publishing was supposed to be its marketing muscle: You may not publish exactly the books you’d like to, but the ones you publish will get the attention they deserve. Yet in recent years, more accurate internal sales numbers have confirmed what publishers long suspected: Traditional marketing is useless.

“Media doesn’t matter, reviews don’t matter, blurbs don’t matter,” says one powerful agent. Nobody knows where the readers are, or how to connect with them. Fifteen years ago, Philip Roth guessed there were at most 120,000 serious American readers—those who read every night—and that the number was dropping by half every decade. Others vehemently disagree. But who really knows? Focused consumer research is almost nonexistent in publishing. What readers want—and whether it’s better to cater to their desires or try harder to shape them—remains a hotly contested issue.

via nymag.com

What kind of large corporate entity doesn't do simple market surveys?

So these guys routinely buy print ads at artsy magazines without looking at its effectiveness?

What about simple reader surveys?

Tuesday, December 22, 2009

Calling @Doctorow "the last, best hope" for SciFi is a bit much. But he is awesome.

It's enough to make you think he really is the Chosen One.

via bnreview.barnesandnoble.com

Lego goes the extra penny for users — UX Hero

See those extra Lego pieces? Those are the ones most likely to be lost either by the manufacturing process or by accident when a kid (or I) build the thing.

Meanwhile, I’ve purchased plenty of build it yourself furniture from places like IKEA or CB2, and they almost always leave out a 2¢ screw. And it’s almost always some special screw that the local hardware store doesn’t have. Fun right?

Note that leaving out a 2¢ part is worse than a big all-at-once failure. With a big failure both you and the store know how to fix it. With a missing screw failure you think, “can I live without this screw or do I drive all the way back there with a half-built book shelf because they screwed me to save two cents per unit?”

Penny wise, pound foolish.

The user experience design version of this is “not going the extra mile to make the experience frictionless.” Yes, it costs more to do, but the downstream effects are huge.

Related Post: Augmented Reality at the Lego Store.

via uxhero.com

Monday, December 21, 2009

Ebooks vs Hardcovers: which is more profitable?

For instance, 40% of hardcovers are either resold online two or three times or lent to friend and family two to three times. Or swapped two or three or more times.

None of those transactions pay a penny to the publisher or the author.

But e-books can’t be resold. Or borrowed. (Barnes & Noble’s Nook offers publishers the option to lend once, but few allow it.)

via publishingperspectives.com

I have been thinking about this ever since I learned that the Kindle is DRM-ed. Even if it wasn't, transferring files from one device to another is always difficult and annoying.

I never realized the Hardcover secondary market is so big.

Texas -- no bookstores here.

Laredo (pop. 250,000) the largest US city with no bookstore. (The nearest substitute will be in San Antonio, 150 miles away.)

via csmonitor.com

Just found out that the two largest cities without bookstores in America are both in Texas.
Laredo and San Antonio.

Sunday, December 20, 2009

Paul Carr is giving away his book!

via techcrunch.com

... and the best part is his excellent writeup on why he is doing it

Thursday, December 17, 2009

Die #Framemaker Die!

In 2009, there is still no truly likeable—let alone standard—editing and authoring software for XML. For many (myself included), the high-water mark here was Adobe’s FrameMaker, substantially developed in the late 1990s. With no substantial market for it, it is relegated today mostly to the tech writing industry, unavailable for the Mac, and just far enough afield from the kinds of tools we’re used to that its adoption represents a significant hurdle. And Frame was the best of the breed; most of the other software in decent circulation are programmers’ tools—the sort of thing that, as Michael Tamblyn pointed out, encourages editors to drink at their desks.

via thinkubator.ccsp.sfu.ca

After the horror of learning the basics of Framemaker, I spent the last two years looking for an alternative -- any alternative -- to this Adobe abomination.

After trying wiki and CMS, editors, Eclipse, etc., nothing still just works.

This solution seems close. Tho, no cigar. It's a lot clumsier than I think is warranted. Why not do a custom CSS for paper? Or push it thru LaTex?

New level of awesome. PastryKit (sort of) works on #Android

Enter PastryKit. As Daring Fireball explains, this combination of JavaScript, CSS, and some supporting graphics resources was created and used by Apple to make the latest version of the iPhone User Guide. When accessed from mobile Safari, a special iPhone-formated version loads up, which perfectly mimics native application look and feel. It does so by explicitly limiting the view to an iPhone screen-sized rectangle, hiding the mobile Safari toolbar, and allowing for the creation of fixed-position toolbars. All input is then intercepted by JavaScript functions, which then handle scrolling in a manner that is as close to native as anyone has yet to manage.

via arstechnica.com

I am loading the Apple User Guides now on my ADP1 with the Dolphin Browser. As long as you set the user agent to "Iphone", it will work.

Well -- sorta.

Everything displays and all the links work. But it never seems to finish loading. I guess some of the javascript bits are throwing the Android javascript interpreter into a loop. Also, I set the default to "Large Fonts" for my browser. This seems to skew the layout on all the pages.

But the cool part is that: It works!!

Individuals can no longer register domain names in China.

via thenextweb.com

This is huge ... and absurd.

http://www.crunchgear.com/2009/12/17/crunchdeals-25-off-skagen-watches/

Man, I think Skagen Watches are slick. CrunchDeals: 25% off Skagen watches

via skagen.com

I know. ~$200 for a quartz watch.
But they are so thin!

They are like ipod touches on your wrists. Except they only tell time.

Because modality sucks. Tab-Modality in Chromium

Because modality sucks.

via blog.chromium.org

Now, we have to tell all the Vim users.

Tuesday, December 15, 2009

Lou Reed's new Iphone App.

Friday, December 11

Lou Reed Launches iPhone App That Has Nothing to Do With Lou Reed
Cut down on chronic iPhone squint with the Lou Zoom.

Photo by Kirstie Shanley

You know when you go to your grandparents' house and they have one of those phones with really big number buttons and it's sorta sad? Well, Lou Reed's new iPhone app is the iPhone equivalent of a telephone with big numbers on it.

It's called Lou Zoom and it enlarges the names and numbers on your contact list "allowing you to read your contact info without squinting," according to a press release. It also makes searching your contacts a bit easier.

And, just in case you think this utilitarian app may have been created by another Lou Reed (since it has nothing to do with music or art or anything), no dice-- the Lou Zoom is currently featured prominently on The Lou Reed's official website.

The application costs $1.99 and you won't need your reading glasses to appreciate the screen shots below the fold:

Posted by Ryan Dombal on December 11, 2009 at 4:15 p.m.

Tags: iPhone, Lou Reed, WTF

Continue Reading →

via pitchfork.com

Everyone is in the Iphone app game now.

Monday, December 14, 2009

FSJ: Why the mainstream media is dying

via fakesteve.net

Wow. I didn't know NYT did an article then.

This is just awful. Maybe newspapers do deserve to die.

Saturday, December 12, 2009

Fake Steve Jobs on AT&T. This is why carrier companies will never be consumer companies

So we set up a call with Randall this morning to discuss some of the profoundly stupid things his guy Ralph de la Vega said recently about creating incentives that would encourage people to stop using AT&T’s data network so much. Point of the talk was, when you’re lucky enough to create a smash hit product — when the stars align, and the hardware is great and the ecosystem is great and the apps are great and the whole experience is great, and everything you do just makes everything else better, and you’re totally on a roll and can do no wrong — when that happens, you do not go out and try to fuck it all up by discouraging people who love your product. What you do, instead, is you fix your fucking shitty ass network you fucking shit-eating-grin-wearing hillbilly ass clown!

via fakesteve.net

Friday, December 11, 2009

McSweeney's Internet Tendency: How the Apocalypse Would Happen if Heaven Were a Small Non-Profit.

HOW THE APOCALYPSE WOULD HAPPEN IF HEAVEN WERE A SMALL NON-PROFIT.

via mcsweeneys.net

This is my life.

sigh.

Worthwhile Canadian Initiative: Car insurance, home ownership, and efficient markets

Car insurance, home ownership, and efficient markets

I don't insure my car. Well, I have liability insurance, but I don't insure the car itself. So if I drive it into a ditch, or it gets stolen, I have to pay to repair or replace it, out of my own pocket.

via worthwhile.typepad.com

This article pretty much sums up all my thoughts on buying vs, renting and car ownership, and how so much of it is a scam.

Thursday, December 10, 2009

The distance between the F and OSS amazes me.

This is why I have always maintained that drawing a political line between so-called “open source advocates” and so-called “free software advocates” is specious. You can’t have “open source software” (in the sense that open source advocates mean the words) without also having “free software” (in the sense that free software advocates mean the words). Both are merely contractions of “free-licensed open source software”. The definitions promoted by both groups (the “Open Source Definition” and the “Free Software Definition”) include both legal freedom to modify and share the code and the pragmatic access to it.

via freesoftwaremagazine.com

Man, I had this giant debate last night on this exact same topic over the phone.

Free Software!
Open Source!

I guess there is a difference, but as an end-user, I don't really care.

I just want to know when they will let me watch pure TV and play cool RPG's on my eeePC.

RRW: Facebook Game Addicts "Paid" to Oppose Health Care Reform

Got that? An aggregation-heavy blog quotes a Flash game CEO blaming a casual game ad network (who denies it) for serving up in-game currency offers from a health-insurance front lobbying group to millions of people who spend their time doing things like watering crops that don't really exist on Facebook to instead send letters to politicians opposing government reform of the health care system. That long sentence went from vacuous to real serious, there at the very end.

via readwriteweb.com

This is a superb sentence!

Remember when being compared to Dubai was a good thing? "Why Greece Could Be the Next Dubai - TIME"

Why Greece Could Be the Next Dubai

By Adam Smith / London

via time.com

Wednesday, December 09, 2009

Why do they always call them ex-pats?

It’s a cocoon, perhaps, or an escape. It used to be worse. There used to be one bar where all the ex-pats went. It was just like in Prague where there where, for years, there were only one or two spots they flocked to, where they isolated themselves from the tumult of a post-Communist society.

via crunchgear.com

People of color never get called ex-pats when they move to "the West." And if POC all gather at one place like that, cops probably gets called.

Tuesday, December 08, 2009

"Immigrants are better at business because they don't know the rules"

I personally believe many immigrants or children of immigrants fare well in business. It never occurs to them to play by the same rules as everybody else; in fact, I’m not sure if they even know what the “rules” are.

via venturehacks.com

Gee. Thanks?

It's always so weird to see technical analysis in a mainstream medium

What we can see is that there is resistance at $28 that has to be overcome. But if your investment horizon is forever then I would say it's not a stretch to think that eventually man's propensity to create solid waste will drive greater profits to the bottom line of Republic Services.

via theglobeandmail.com

http://www.google.com/dictionary

Friday, December 04, 2009

Google made a dictionary

http://thelostjacket.com/marketing/invert-funnel-functionality-trumps-design

Wednesday, December 02, 2009

Link: User Interface is marketing

It should be obvious by now. This article sums it up nicely. Mad Man reference is extra bonus.

Goldman bankers are buying handguns as a hedge against revolution

senior Goldman people have loaded up on firearms and are now equipped to defend themselves if there is a populist uprising against the bank.

via bloomberg.com

Oh man.
This thing is funny on sooooo many levels.

The funniest part is that it's from Bloomberg.
I guess if you're the real rulers of the world, a little protection goes a long way.

Thursday, November 26, 2009

Quote: Typographical Snobbery "Gill Sans smelled of soap, and tasted like bakelite."

Gill Sans smelled of soap, and tasted like bakelite. Palatino sounded like a Eighties-era synthesiser handclap. Times New Roman smelled of engine oil. Bembo felt like velvet.

via blog.bookoven.com

A beautiful essay on type.

via "The White Negro," - Norman Mailer, Dissent Fall 1957

Tuesday, November 24, 2009

Netbooks at Best Buy in Toronto

Think of this as a special request. A friend of mine asked me about netbooks and CULV's today.

After discussing his perceived needs, I threw around a few suggests. He liked some of them, but talk is talk.

So after work, I went down to the Best Buy at Downsview to try them out.

This is actually the best deal going on right now. Speaking as a Mac user, this CULV is almost good. I am actually thinking of buying one. The trackpad is almost usable. The keyboard is full size, except for the weird placement of the Enter Key. The only bad thing here is Vista. But hell, it's not the end of the world. And the price is definitely right.

There was also a HP Mini 10 and a Toshiba for the same price, but I think the Gateway still beats them both.

Fortunately, Liliputing already did an excellent review of this.

What is a "Hipster" according to Norman Mailer in 1957?

It is on this bleak scene that a phenomenon has appeared: the American existentialist—the hipster, the man who knows that if our collective condition is to live with instant death by atomic war, relatively quick death by the State as l’univers concentrationnaire, or with a slow death by conformity with every creative and rebellious instinct stifled

I don't think it means that anymore. Although hipsters are mostly still white.

Link: The hidden cost of product segmentation — UX Hero

The hidden cost of product segmentation

Artificial market segmentation works, in that it can make money, but there is a hidden cost:

Don’t make me think. Don’t make customer support harder. Don’t create confusion pollution.

Your customers will thank you.

Seth Godin says, “if you have more than seven items in a pull down list, you have failed.” I agree, especially when every item is identical except for words like “Professional” and “Ultimate”.

via uxhero.com

Ditto!
I was trying to figure out which version of Vista I needed last year.

It took two days of research. Those are two days I will never get back. My two days are worth a little more than the price of their software.

Newsweek (Why We Tumbl)

Most publishers tend to think of the things their audience has to say as, at best, graffiti that they allow to be put on the sides of their nice building. One of the many beauties of Tumblr is that it gives the audience equal footing. There’s a real communication here, not just a lot of people shouting across the comment ghetto to each other, and that’s a rare thing that we should encourage.

via newsweek.tumblr.com

Of all places to find something so insightful... Newsweek.

Quote: Our Internet Ignorance of Yesteryears

Flashback to eleven years ago. The graphic designer tells me to publish the entire body text as a JPG because her choice of fonts is not available on browsers. I, an intern having no say in the matter, do it, but feel dirty.

via quirksmode.org

Sunday, November 22, 2009

CanLit is horrible.

Tuesday, September 22, 2009 11:06 AM

A Brit Giller judge makes fun of Canadian fiction

Peter Scowen

From there, she took a more critical pass at Canadian fiction, noting that the mid-list material coming from many publishers has a "striking homogeneity":

There is a convention in Canada of appending to your novel a list of people who are fulsomely thanked for their support, starting with the book’s editor – unfailingly sensitive, creative and patient – plus family, friends and first readers. These last are generally fellow members of a writing group, who have contributed insightful modifications.

But has any major work of art ever been produced by committee? Readers may wonder whether a writer’s vision and voice may not get ironed out by such proactive input, and indeed there is a striking homogeneity in the muddy middle range of novels, often about families down the generations with multiple points of view and flashbacks to Granny’s youth in the Ukraine or wherever.

The US, too, is a nation of immigrants, but American novelists do not bang on so about their heritage and antecedents.

Fully wound up now, she delivered the coup de grace, suggesting that mediocre writers of "unbelievably dreadful" novels benefit by being Canadian:

It seems in Canada that you only have to write a novel to get grants from the Canada Council for the Arts and from your provincial Arts Council, who are also thanked. Complaints were once voiced that most shortlisted Giller novels emanated from just three big-name publishers, all owned by Bertelsmann, and that virtually every winner lived in the Toronto area. Now, many of the submitted authors, and their rugged subject matter, hail from Saskatchewan, Manitoba, Nova Scotia, Newfoundland. That’s maybe because small publishers too are now subsidised, and they proliferate. If you want to get your novel published, be Canadian.

via theglobeandmail.com

Totally agree. There are so many crappy CanLit floating around like baby seals staring dumbly on ice floes waiting to be clubbed.

I remember as a kid, I used to read a novel a week. I would all the fiction books at the library except for the ones with little maple leafs taped to the spine. They were always so dreadful. Humourless. Dull. Boring characters. Meandering plot lines. And dialogs like the skins of rotted fish.

I rather like Canada, my adopted home. And the people I know are interesting and great people. They deserve better representation than what they're receiving from the current crop of "Canadian" authors.

Saturday, November 21, 2009

Why Google Wins.

The War For the Web

by Tim O'Reilly

One of the points I've made repeatedly about Web 2.0 is that it is
the design of systems that get better the more people use them
, and that over time, such systems have a natural tendency towards monopoly.

And so we've grown used to a world with one dominant search engine, one dominant online encyclopedia, one dominant online retailer, one dominant auction site, one dominant online classified site, and we've been readying ourselves for one dominant social network.

A few months ago, I was talking to my friend H. about Web 2.0

We use to talk about startups a lot, but he decided to go to do an MBA in HK instead. So he is kind of missing on the new Web 2.0 hype-engine.

I was trying to describe to him A/B Testing and used Google as an example. He asked, "That's it? So why can't we replicate what Google does for UI design?"

I didn't even have to think about it to give him the answer, "Because Google is more disciplined. They have a willingness to follow their methods and apply it everywhere to a degree no other company can match."

Hell, look at Microsoft or Yahoo. They have money, talent, and drive. Why can't they make something a fraction as good as gmail? And I am a paying Yahoo Premium customer. I'll bet Yahoo makes more money than Google on webmail --- right now. But they probably won't for long.

Ditto. Why we all like Microsoft, even if they're lame.

I think about Microsoft a lot. I’ve got a soft spot for them. I remember launching games like Battle of Britain and Wing Commander from the DOS prompt. I remember learning Photoshop and playing Quake 2 on Windows 98. I remember assembling my first PC with friends. Happy memories.

So why do I use a Mac today? Why can’t I even imagine going back to Windows, even if my livelihood depended on it? And why do so many other former Windows users feel the same way?

Erosion.

Every day Microsoft caused us a little more pain. Every bad experience wore us down a bit more, and Microsoft wouldn’t or couldn’t fix it. Then a friend would switch to Mac and rave about it. Then another. And then one day we found ourselves in the Apple store, ready to believe.

Notes:

More posts about brand erosion are in the pipe. Understanding why customers leave — especially when it’s painful or expensive for them to do so — is vital in understanding how to keep them.

More on this later, but I believe Internet Explorer’s legacy of suck is a huge part of Microsoft’s undoing.

via uxhero.com

On a side note, I still have an old laptop at the foot of my bed that runs win98.

I was still running win2k on my Macbook until a year ago.

Friday, November 20, 2009

Nokia N900 is out!

via thenokiablog.com

This looks like the coolest phone ever ... in another two years.

By no means a snide comment. I am really excited over this. But it still need sometime to grow and mature. The telephony software is still fairly new. Just looked at the Maemo page and it already has more apps than Palm's WebOS.

The space button on one sides is silly. Also, making the enter key the same size as everything else is also a bad idea. Need more time and dev and polish. But it is going to be geeky-cool.

Wednesday, November 18, 2009

On the nonsense from out-of-touch, non-black Baby Boomer journalists.

I just read a story about Lawrence Hill's Book of Negroe's bestseller which stipulates that he "broke the publishing industry’s rule that black novelists don’t sell". That is some extremely corny prose. Black novelists in Canada don't even get a fair shot to get published, much less sell. That's why I'm going to set up an imprint in a few years, and disprove much of this nonsense being written by this particular brand of out-of-touch, non black Baby Boomer journalist. There are so many dull and uninteresting Canadian novels being put out there on the marketplace, and publishing contracts being handed out to authors who members of my writing group can outright out-write with their pinky finger, yet they get no traction because they don't go to the right parties, might not have the correct last name, aren't of the right racial designation, have no privileges bestowed upon them by birthright. It's like whatevs. The show must go on. Our ancestors have endured far worse ignorance, and it's 2009, so ain't no one waiting around for some analog journo to give my Generations wordsmiths their stamp of approval.
Globalization is real. It's not 1982...the takeover is imminent.

Yours,
The Lawrence Hill of Hip Hop

via openbooktoronto.com

Exactly.

NYT: The Self-Manufacture of Megan Fox

via nytimes.com

A really, really sympathetic piece on Megan Fox as an "real person" instead of a pinup girl.

It's nice. I like it a lot. I don't know which part is true, since the whole article is about the artificial persona that Megan Fox purposely built (Fox talks about it quite extensively in the article.) In a very meta kind of way, this article about Megan Fox's fake persona is also a part of creating her fake persona.

Whoa!

Tuesday, November 17, 2009

Tech Comm: Text vs Illustration -- Visual Methods of Communicating Structure, Relationship, and Flow :: UXmatters

via new.uxmatters.com

It's true.

At my current job, I hardly ever write. I spend most of my days doing Swimlane diagrams. I personally think the things are useless. I am a writer, dammit! Let me make beautiful sentences about the Departmental Systems Requirements!

You know what? Everybody glazed over my on my detailed 8-page instruction. But, the one page swimlane diagram? They love it! (Well, they love it as much as anybody can for technical material.)

Anyways, point is, TechComm is all about ... communication. As long as you can get your reader (looker?) engaged, excited, and understand the material, whatever you use, it's all good.

Writing great documentation: technical style

Now that I’ve discussed what kinds of technical documentation to write, I can move on to the question of how to actually develop a writing style that produces great technical documentation.

Learn to write

Unfortunately, there aren’t any shortcuts here. The best way to learn how to write great documentation is to first learn how to write (anything). There are some important differences between technical documentation and your average prose, but a solid foundation of good written communication skills is an irreplaceable prerequisite.

So how do you learn to write (anything) well? There’s only one answer: you’ll learn to write well if you write. A lot.

Writing English isn’t any different than writing code: the more you do it, the better you get. You could take a class — most community colleges have pretty good beginning writing classes — but the important part really is to just write a lot. Over time, you’ll get better.

That’s how those of us with humanities degrees (I’ve got a degree in American Literature, also known as a “B.A. in B.S.”) become good writers: our degrees force us to write to the point that it comes easily. I think I wrote about ten to twenty pages a week each of my four years in college. That forced me to internalize grammar and form a personal style.

You’ll probably want to balance out all this writing with a healthy dose of reading, too. Learn to identify the mechanical parts of what makes a piece of writing effective; try to identify what succeeds (and what fails) about everything you read.

Watch for how authors accomplish “tone”. Read through a number of pieces by the same author; you should be able to identify what makes that person’s writing distinctive. Malcolm Gladwell would be one good choice here: his writing style is quite distinctive, somewhat formulaic, and he’s got dozens of his articles online. Most importantly, Gladwell’s style is one that’d work very well for technical documentation — he’s got a breezy, fun, conversational tone that nonetheless can communicate specific technical topics clearly.

It doesn’t matter all that much what you’re writing and reading. Sure, there are different rules for fiction and non-fiction, literary criticism and technical documentation, etc. The important aspects don’t change, though: good writing is clear, succinct, and communicates ideas effectively.

Most importantly: don’t let style stop you. In a moment I’m going to start covering the rules and suggestions of good grammar and style. It’s easy to get caught up in wanting your prose to be perfect from the first words you set down. It does’t work that way. While you’re writing, turn off the inner critic and just write. You can turn the critic back on when you proofread and edit later, but the important part is to just do it. Please don’t let anything else I’m about to say get in the way.

Grammar

Yes, you do need to use correct grammar. Grammar conventions exist to help us clearly communicate our thoughts without ambiguity or confusion. You need to understand the difference between “its” and “it’s;” between “there,” “they’re,” and “their;” and you need to understand why I’m putting the commas and semicolons in this sentence inside the quotes, not outside. (Since my audience is mostly programmers I shouldn’t have to spend extra time explaining why the consistent positioning of semicolons is so important!)

If you went to public school in the US you probably learned this stuff. If your public school was anything like mine, you probably forgot it all shortly after the final.

Again, a writing class could help if that’s how you like to learn. Me, I have a few of books that never leave my side:

Strunk and White’s The Elements of Style is probably the best-known grammar and style text. Its pithy, witty style makes it an actual pleasure to read — very unusual for grammar texts. It’s a bit long in the tooth these days (in fact, there’s recently been a bit of a backlash against some of the advice S&W gives), but if you take Strunk and White to heart you’ll be head and shoulders above the average writer.

(There’s also a really beautiful 50th anniversary edition if you want an edition that’s bound in a way befitting the work’s stature.)

Diana Hacker’s A Pocket Style Manual. This is a no-nonsense, quick-reference-style guide to grammar, punctuation, and mechanics. As a bonus, it has a quick-reference to the Chicago Manual, Modern Langauge Association (MLA), and American Psychological Association (APA) style guides.

I use it less frequently, but I also find the Handbook of Technical Writing useful. It’s a huge and comprehensive A-Z guide to language — there’s a section on “its” and “it’s,” one on the phrase “no doubt but,” and so on. (I’m sure there’s a section on “and so on.”) I’d recommend against diving into this one head-first; use it as a reference when you need to know the rules for using some particular phrase.

Style

Wait, back up. WTF are style guides?

While grammar rules are (fairly) set in stone, there’s any number of ways of formalizing style. Style guides tell you when to spell out numbers and when to write them as digits, where to use em- and en-dashes, how to cite sources, and all other manner of arcana.

The three that Hacker covers — Chicago Manual, MLA, and APA — are some of the most commonly used in academic publications. The Chicago Manual is popular in social science and historical settings; the MLA is used by most literary, media, and cultural publications; and the APA guide forms the basis of most scientific style guides. There are plenty of other style guides out there — large publications like the New York Times and the New Yorker have their own house style books — but unless you’re a total language geek they make pretty boring reading

The Django documentation mostly follows the Associated Press stylebook as a sort of homage to Django’s roots at a newspaper.

In the end, though, it really doesn’t make a whole lot of difference. The important lesson from all this is to be consistent. Readers find different stylistic choices off-putting, and they lend an uneven, unfinished tone to the documentation. Choose a stylebook, learn it, and then follow it… sometimes.

Good documentation style

Of course, careful breaking of the rules turns good writing into great writing. Most of the style rules you’ll find in these guides are oriented towards academic material, but I’m trying to help you write better documentation. There are important differences. Most style guides assume that writing will be presented in printed form, but most technical documentation is consumed online.

It’s well-known that people actually read differently on a computer screen; it’s probably also true that people read technical documentation differently from academic material.

Thus, the rest of this article will cover the areas that good documentation deviates from the standard “write well” advice in S&W, Hacker, and others.

Markup

There’s one huge difference between the way people read print and the way they read electrons: when people read online, they skim. Study after study has shown that readers skip a large percentage of the words that float by on their computer screens.

This means that good online documentation will feature a much heavier reliance on markup than most style guides allow for. In practice, this means:

Use inline markup liberally.

Mostly, this means using emphasis and strong text frequently. I usually avoid too much strong because it’s looks like I’m just aping Jakob Nielsen, but whatever. Similarly, use markup for things like code samples, entry versus output, and the like.

This breaks up the monotony of large chunks of text and lets users skim between the different “important” parts of your document.

Write in short paragraphs.

If you compare good documentation to a typical magazine article or book chapter you’ll quickly notice a big difference in paragraph size. A book might have paragraphs that are ten, twenty, or dozens of sentences long, but it’s rare for good online documentation to even measure up to half that. The longest paragraphs in this document are about five or six sentences long.

Again, readers skim digital content. Breaking up your thoughts into smaller pieces facilitates this flow and ensures that important point don’t get missed because they’re buried in the middle of a wall of text.

Use a variety of structural elements.

Academic and journalistic writing don’t usually feature lists, tables, code blocks and the like. Most style guides omit advice on using them, or even prohibit their use. But they’re vital in technical documentation: tables and lists are particular important ways of presenting material.

Note

Callouts are especially useful; they can call attention to bits of content that might otherwise get lost, provide amusing or interesting digressions, or indicate that a particular bit of information is especially important.

Make your structure visual.

Your high school English teacher probably taught that section headers are “bad style” and that your whole paper should “flow” together. While flow’s important, it’s hard to accomplish in technical material. If you push it, you end up with pointless transitions — “now that we’ve talked about URLs, let’s talk about models!”

Headers are especially important to get right: they’ll stop skimmers as the fly by down the page. Headlines help reader quickly find the section of the document they’re looking for.

The above might seem obvious to those who’ve been writing for the web for some time. That’s the point; most technical documentation is consumed online, so most of this advice comes down to simply optimizing the content for the different task of reading online material. Print-designed material suffers when read online, so as you read about writing style always question whether the advice applies online.

Style

Online readers of technical material have different expectations of style. There’s a certain style that plays well to medium of online material and also helps facilitate the learning process that documentation is supposed to be facilitating.

Mostly, this style comes down to being approachable. Most style guides are oriented towards academic environments, and academic writing is notoriously stuffy. Expectations are different online, and what might be appropriate for a literary criticism journal just comes across as antiquated and obtuse online.

So I suggest:

Be conversational.

Write in a tone similar to how you talk. This doesn’t mean including all those verbal tics (“well…”, “you see”, “um…”), and it doesn’t mean throwing grammar rules out the window. If you use “gonna” in a technical document I’m “gonna” hate you.

But it does mean that contractions are okay, as is starting sentences with conjunctions.

Don’t be afraid to strike a personal tone.

You probably learned never to use “I” in a formal essay. Well, I’m here to tell you that it’s just fine in technical work. Showing your personal voice helps readers identify with the material, and that makes the material less intimidating.

You do need to be careful to be consistent with pronouns in collaborative works. You might choose to always use “I,” even in works written by different authors. Leonard Richardson and Sam Ruby took this path in RESTful Web services. Or you might choose to use “we”, even in parts written by a single author. Adrian and I went this way in the Django book. As long as you’re consistent, either approach works.

Do be careful with tenses and persons.

Most documentation, and especially tutorials, is written in the second person, future tense. That’s stuff like “first, you’ll need to install FooBar version 7. Then, when you’ve frozzled the whizbang, you can start working on the doodad.” This is the general form I prefer since documentation is essentially instructional material and I like the conceit that I’m personally instructing my readers.

Another common form is to couch everything in the first person plural: “first, we’ll need to install FooBar version 7…” This has advantages: it implies that the author is right there in the thick of things with the reader. But it can lead to confusion if later the author wants to be more conversational.

Once again there’s no “correct” way here, but you’ll want to think about this question, figure out a standard, and stick to it.

Watch out for passivity.

You’ve probably learned to avoid passive voice in your writing. That’s usually good advice, but it’s not the whole story; what I mean here is that good technical writing is active. The verb always appears first. Remember: you’re instructing people, so make it clear what to do at all times.

To illustrate, my first draft of the above paragraph started, “your high school English class probably taught you that passive voice was bad style.” That’s not passive voice (“… English class… taught…” is plenty active), but it does obscure the actual action in question — what “you… learned”. Starting the sentence with “you learned” brings the focus back onto you, the reader, hence keeping with the conversational, instructional tone I’m trying to strike.

Omit fluff.

This is best illustrated by example. Yesterday’s piece contained this ugly sentence:

This means that it should be pretty cross-sectional; a good tutorial should show off most of the different areas of the project.

A commenter (rightly) took me to task for this one: this sentence has a number of words (“pretty”, “most”, “good”) that don’t add any meaning to the sentence and some others (“different areas”, “the project”) that are vague.

Here’s a better version:

This means that it should be cross-sectional; a tutorial should show off the major areas of your project.

The meaning’s the same, but the second version is more forceful, clearer, and shorter. This is good.

Watch out for written tics.

Everyone’s got certain bad habits when it comes to writing. I think of these as written tics: little habits that have become nearly involuntary. Once you notice a writer’s tics it’s hard to stop noticing. The repetition just gets in the way.

For the record, my written tics are an over-reliance on semicolons and em-dashes; this document contains far too many — of each.

What’s next

All these rules can be incredibly overwhelming, I know. However, there’s a magical being that knows these rules and will remember them and apply them to your writing so that you don’t have to!

I’ll talk all about these magical creatures in tomorrow’s episode, titled: “You need an editor.”

via jacobian.org

I don't blog very much about Tech Comm. Partly, it had to do with the fact that in the last 3-5 years has fallen in to a new Dark Age.

I blame DITA.

Anywho, found this article in my inbox and it is just awesome for anybody who needs to write. Short and succinct. Full of good advice on modern writing.

Monday, November 16, 2009

Questionable Content: #468

via questionablecontent.net

Gee,

I started blogging around the same time as well on Blogger. It was a bit late, but it was also when I first got my Hiptop (Sidekick.) That phone was awesome!

I remember I picked Blogger because they had the best mobile blogging features at the time. (IMHO!)

Go@Blogger.com

Actually, it still is pretty good. I use Posterous now, but Blogger is still ok.

Saturday, November 07, 2009

Emoji

I just found the extra emoji option in Gmail.

Gee

Why are these things standard options on all cellphones and computers?

Thursday, November 05, 2009

"Relate well with people"

I am on the subway right now.

There is a under-produced, "let's photoshop our logo on stick photo we found," "earn extra income" scammy, job ad above me.

I don't know what this job is all about. But they are asking for someone who is "an independent spirit" and "relate well to people."

Really.
Who is going to say that they don't "relate well to people?"

In democratic regimes, everybody thinks they are independent and friendly. It's part of democracy's promise. Liberty and Fraternity.

Why is this ad here and what sucker is actually "working" for them?

Thursday, October 22, 2009

Facebook Launches New Mobile Touch Site

via feedproxy.google.com

This is so cool!

It's a better version than the iphone "optimized" site. And light years better than the generic mobile site. But my fav is still Facebook Lite: it's the most functional way to access Facebook on my G1.

http://www.msnbc.msn.com/id/33092510/ns/business-businessweekcom/

Tuesday, October 13, 2009

Starbucks: VIA Ready Brew is a stupid idea

I know the economy is going badly and Starbucks is scrambling for cash, but degrading their premium brand is probably not going to end well.

For the press release disguised as a news article version, see:

It's funny as all heck to be ding by Wall Street Journal:

http://online.wsj.com/article/SB10001424052748704471504574447070743132740.html?mod=googlenews_wsj

What product did he point to as the canary in the coffee mine? Instant coffee. Mr. Wu [Former Director of R&D for Starbucks] called it "a product of last resort."

This week Starbucks gave the full nationwide rollout to its new line of instant coffee.

and also,

Which doesn't mean Starbucks instant coffee tastes bad. It's very good, as far as instant coffee goes, and not terrible when compared with a regular cup of brewed coffee. Just drink it fast, while it's super hot. Warmish Via has a slightly pasty quality.

Adweek hits the nail on the head:

http://www.adweek.com/aw/content_display/community/columns/other-columns/e3i03c5991d65201a601ccc055d207034f0?pn=1

the question remains whether this is a solution in search of a non-existent problem. If the consumers now willing to pay more at both the store and in the aisle for Starbucks don't want an instant, that leaves Via to Nescafe and Sanka users. It's difficult to imagine that most folks now using the big instant brands at a fraction of Via's price will suddenly be willing to spend far more for a taste they haven't felt the need to pay for before, particularly in the current economic climate.

Sunday, October 04, 2009

Story about shoes

Audience told stories about their shoes.

Sometimes people rhyme.

Disaster and jazz

Small Mercy

People are giving out rations of small sausages, cocoa, and blankets.

And they had a small jazz band.

Free Drinks from the Master Blender

Where it stops, nobody knows. serves a mean ice coffee.

Paper Bag People

you try to walk by, they block you. then they apologize.

via Pixelpipe

Take Shelter, 2009

Audience is encouraged to build shelters with cardboard boxes and to donate or take can goods.

Nurses (not really) at Nuit Blanch

At the distillery right now, I am not sure what this is about. Hot nurses. Of both genders.

Saturday, October 03, 2009

waste: This be close reading

This line, which begins Larkin's poem, "This Be the Verse", so forcefully, has long been a puzzlement to scholars, who have debated amongst themselves since its publication what the meaning of "fuck you up" might be. I believe that the key to understanding the line, which recapitulated and varied in the other quatrains (thus giving the poem the structure of a partially-deranged sonata), lies in the preposition, "up".

via waste.typepad.com

This is why Textual Analysis should be banned.

Moon Festival

It's the moon festival today. This is the aftermath of many, hungry members of my family. These are their spawns.