38 ms·
I think good technical writing is a lot like good interior design. My brother is an interior designer who has done lots of work for hotels. He says that as an
by jonathanlydall 1y ago
I think good technical writing is a lot like good interior design.
My brother is an interior designer who has done lots of work for hotels. He says that as an interior designer, people typically only notice your work if you’ve done it badly.
If you use a decently designed hotel room you don’t think much of it, but if it’s got problems like badly laid out space, even if you can’t quite put your finger on it, it feels “off”.
If a reader doesn’t have any opinions on a technical article and got the information they were expecting, then it’s probably well written.
When I write technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally as possible.
- throwaway328 1y agoMaybe 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.
- patcon 1y agoA 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.
- golergka 1y agoAh, the Ballmer peak.
- Y_Y 1y agoSee also: Stephen King, Oscar Wilde, William Wordsworth.
- throwaway328 1y agoHunter S Thompson, James Joyce, Charles Bukowski, John Fante, Knut Hamsun, ...
- achenet 1y ago"write drunk, proofread sober" - Ernest Hemingway
- Y_Y 1y agoComment drunk, revise never! https://quoteinvestigator.com/2016/09/21/write-drunk/ 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.
- jklowden 1y agoBrian Kernighan cannot be topped. He is easy to read, succinct, clear, and sometimes funny.
- achenet 1y agoI 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!
- throwaway328 1y agoAbsolutely 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
- ajdlinux 1y agoThis 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.
- throwaway328 1y agoI 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.
- wyclif 1y agoI wish the Chicago Style Guide or MLA was organized like this, freely available, and open source. It would be a boon for writers everywhere.
- epicide 1y agoYou 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?
- deepsun 1y agoPeople also notice your work if done badly in accounting, security, QA.
- ignoramous 1y agoExtending the Interior Design metaphor, the context of what's being designed and for who, that is, the doc archetype (manual, tutorial/guide, reference, recipies/demos/samples, audience-specific), is the first important part to get right. https://github.com/google/opendocs/tree/main/project_archetypes https://github.com/google/opendocs/tree/main/project_archety... > technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally why do people read docs ... because they want to achieve something ... you need to work out what problem your reader is trying to solve. If Dusty wants to put their degree up on the wall, they might want to consult some documentation about how to do it. The documentation Dusty needs to do this would probably not be called "How to Choose a Drill". The documentation Dusty needs is "How to Hang a Picture". https://www.thegooddocsproject.dev/tactic/ia-guide https://www.thegooddocsproject.dev/tactic/ia-guide / https://archive.vn/rgt4Y https://archive.vn/rgt4Y
- latexr 1y agoThat’s far from exclusive to interior design. Any designer in every discipline will be familiar with that notion, regardless of it being interior design, industrial design, graphic design, … “Good design is actually a lot harder to notice than poor design, in part because good designs fit our needs so well that the design is invisible” — Donald A. Norman, The Design of Everyday Things (1988)
- MengerSponge 1y agoIt's the origin of 99 Percent Invisible's name: https://99percentinvisible.org/ https://99percentinvisible.org/ I was about to recommend an episode or two, but it's an institution at this point. If you have a reasoned opinion about flags, there's a reasonably good chance it's because you saw or heard Roman Mars talk about vexillology. https://www.ted.com/talks/roman_mars_why_city_flags_may_be_the_worst_designed_thing_you_ve_never_noticed https://www.ted.com/talks/roman_mars_why_city_flags_may_be_t...
- bmacho 1y agoIs it true? I think people are very vocal about good design (interior or not). If they are not loudly loving your design, then try again.