[jonathanlydall]

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]

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.

[patcon]

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.

[golergka]

Ah, the Ballmer peak.

[Y_Y]

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

[achenet]

"write drunk, proofread sober" - Ernest Hemingway

[Y_Y]

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.

[throwaway328]

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

[ajdlinux]

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.

[epicide]

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?

[jklowden]

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

[achenet]

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!

[throwaway328]

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

[throwaway328]

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.

[wyclif]

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.

[ignoramous]

Extending 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_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://archive.vn/rgt4Y

[latexr]

That’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]

It's the origin of 99 Percent Invisible's name: 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_t...

[bmacho]

Is 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.

[deepsun]

People also notice your work if done badly in accounting, security, QA.