Hacker News Reader

Comment by throwaway328 | Hacker News Reader

Maybe that's a good recipe for reliable technical documents, but arguably not great ones. Some of my favourites writers - Donald Knuth, Leo Brodie, Marshall Kirk McKusick, Harley Hahn, Jeff Duntemann, Beej, Nils Holm, surely missing more - write with a lot of flair and personality. I mean, it certainly doesn't feel cold and lacking in emotion. Oh, Dennis Yurichev too.

View on HN

A friend who ran a mildly popular dev tool (4k+ stars) kept really stellar docs, and his process of updating them was to sit down with a bottle of whiskey every few months, and doing a marathon doc-writing session. the brand voice would come from him being a funny human and getting a little tipsy.

I suspect his silly and fun-sounding "kinda drunk" brand voice was what set them apart from all the other boring dev tools in the space.

Ah, the Ballmer peak.

See also: Stephen King, Oscar Wilde, William Wordsworth.

"write drunk, proofread sober" - Ernest Hemingway

Comment drunk, revise never!

https://quoteinvestigator.com/2016/09/21/write-drunk/

Looks like it was Peter de Vries, but the hallmark of a good quip is shambolic attribution.

Hunter S Thompson, James Joyce, Charles Bukowski, John Fante, Knut Hamsun, ...

This is true, but the general advice one gives through, for example, publishing a style guide, should focus on producing reliable outcomes over great outcomes. I'd happily lose most of the great documentation I've read in the course of my work (not that much) for never having to read inaccurate or woefully incomplete documentation ever again.

You can think of it in terms of tolerances. Beej's (and others you mention) style is like a tighter tolerance: it fits to better effect at the cost of fitting in fewer places.

Personally, I'm in the audience that that style works well on, but I can also see how it might be harder for someone to follow that style. e.g. if English isn't their native language. Similarly, I imagine that style is also much harder to localize (not just translate).

I think both techniques are great and I don't think they're mutually exclusive. That is, you can still inject flavor and style within the confines of a technical style guide. You just do so in a way that's less... flamboyant?

Brian Kernighan cannot be topped. He is easy to read, succinct, clear, and sometimes funny.

I second this. Donovan and Kernighan's The Go Programming Language taught me enough about the language to get my first job in it in less than a month.

Four and half years later, I'm still employed as a professional Go programmer.

Thanks, Brian!

Absolutely on board with you and GP, I forgot Kernighan, I've only looked at a couple of chapters of the C Programming Language, but it was totally wonderful to read yes! He's definitely up there

I really should have included Bob Chassell, of "Intro to Emacs Lisp" fame, what a personable and gentle introduction for beginners! Very beginner-focused, but if you read it as a beginner, it's like your slightly chatty Uncle introducing you to the family business. Which just so happens to be - writing a lisp language to learn to extend a lisp software platform which includes a text editor. I loved it.

I wish the Chicago Style Guide or MLA was organized like this, freely available, and open source. It would be a boon for writers everywhere.

Reply on news.ycombinator.com