Fie! Fie I say to you!
One of the great tragedies of modern technical writing is that it has gotten so fucking standard and boring. There is absolutely no reason for it. It does not make it clearer or easier to read, in fact it makes it worse in every way - less clear, less fun, less human.
If you read actual great technical writing, it has humanity and humor. For me the absolute giants of technical writing are Feynman and Einstein. There's lots of cleverness and little winks for the advanced reader and lots of non-standard ways of writing things. If they followed Boring Technical Style Guide it would suck all the personality and beauty from their writing. (I also like Isaac Asimov's technical writing and John Baez's).
I think computer writing has become particularly bad in the last 10 years or so. The books are all Microsoft-press-style bullet point garbage. Blogs (eg. finger files) started out in the early days as sort of wonderful ramshackle things where each one was different and reflected the writer's personality, but recently there has developed this standard "technical blog style" that everyone follows.
Standard Technical Blog Style is very pedantic and condescending; the author acts like some expert from on high (regardless of their actual expertise level). There are as many self-plugs as possible. I find it vomitacious.
A while ago someone wrote a blog series about floating point stuff; it really bothered me for various reasons. One was that the topic has been covered many times in the past (by Chris Lomont for example, also FS Acton, Kahan, Hecker, etc) (if you actually want to learn about floating points, Kahan's web page is a good place to start). Another is that it just rolled out the same old crap without actually talking about solutions (like "use epsilons for floating point compares" ; wow that is super non-useful advice; tell me something real like how to make a robust BSP engine with floating point code). But maybe the most bothersome thing about it all was that it was written in Standard Boring Dicky Technical Blog Style when you can go out right now and buy a wonderful book by Forman S. Acton on floating point which is not only much much more useful, but it's also written with cleverness and humanity. (Kahan's writing is also delightfully quirky). It's kind of like taking a beautifully funky indie movie and remaking it as mainstream shlock; it's not only a waste of time, but offensive to those of us who appreciate the aesthetic pleasure that is possible in technical writing.
Anyway, if you are considering doing some blogging or technical writing, here is my advice to you :
1. Make it informal. Use I. Use incomplete sentences. Tell stories about your personal experience with the topic. When you put in some really complicated code or equations or whatever, explain what it means with colloquial, conversational english.
2. Don't look at any reference material for a writing style to copy. Their style fucking sucks. Don't copy it. If you listen to people telling you the "right way" to do things, you will be aspiring to mediocrity. (err, ahem, but do listen to me).
3. Do not use an artifical impersonal voice to add "gravity" or a false air of expertise, it doesn't work. Be humble; admit it when you aren't sure about something. Also don't pad small ideas with more text to make them seem bigger. There's nothing wrong with a one sentence idea. 90% of AltDev blogs should be one paragraph or less.
4. Do not waste time editing that could be spent making the content better. I bet you didn't actually run fair comparison tests against competing methods. Go do that instead. I will not judge you by the purpleness of your prose but rather by the content of your creation.
5. Stop writing blogs about shit that is already very well covered in books. Your writing should always be from the perspective of your domain-specific experience on a topic. Don't write yet another introduction to Quaternions, write about how you've used them differently or some application you've found that you think is worth writing about. Real domain-specific experience is what make your writing valuable.
6. Habeas Corpus. Show me the money. If you're writing about some new technique, provide code, provide an exe, prove it. If I can't repro your results, then I don't believe you. Document the tiny details and embarassing hacks. The vast majority of technical writers don't write up what they *actually* use. Instead they write up the idealized clean version of the algorithm that they think is more elegant and more scientific. Often the most useful thing in your work are the hacks for weird cases that didn't work right. People are usually too proud of the main idea; hey guess what, thousands of people have had that idea before, but didn't think it was worth pursuing or didn't get the details quite right; the value is usually in the tweak constants or the little fudgey bits that you figured out.
I think conversational technical documents can be done, but they might actually require significantly more work to pull off successfully than 'boring, dry, standardized by-the-book' technical writing (which pretty much just requires turning a crank to generate). At a minimum you need some sort of consistency so the reader isn't freaked out. By the time people are reading documentation, they're usually failing at getting something to work, and their patience is short. If you have a bunch of standard documentation, then out of the blue there is some conversational stuff in it, it's jarring to read, and for me, it feels broken (plus I'm a judgmental bastard and read too much into things). However ,if it's conversational from the start, and throughout, then it could be great.
ReplyDeleteIn the middleware I've used, the '95% standard, 5% conversational' stuff is actually super common and annoying. Everyone feels like they're chafing at the bit and wants to put their personality into my documentation here and there. Generally I want them to GTFO so I can get my job done. But more than anything I just want it to be consistent.
Totally agree that the focus should be on generating richer content rather details of style. For me that is one of the reasons to use dry technical writing methods, though. I find I pack more content in when I strip the formatting down. Always fun to take a sentence. Strip it down to boring bullet points. Then realize you missed like 5 things you wanted to say. And it frees you up from having to focus on sentence structure and such too much.
In the end, though, it's just documentation. Make damn sure it is correct and complete, cuz no one is going to read it until they can't figure out how to make your samples work (which they'll blindly copy into their shipping product, so make sure those are always the absolute optimum way to architect things, and are what you'd want to ship in a game).
Yeah I'm not really thinking about product documentation so much as expository type writing.
ReplyDeleteBut I'm not nearly as bothered by style inconsistency as you are. Notation and terminology inconsistency = very bad.
But for example the Feynman Lectures has vast style variation from one chapter to the next, some are almost photocopies of lecture notes, some are super dry, and others are very conversational, and it doesn't bother me at all.
Ah yeah. Totally with you there.
ReplyDeleteWay too many people who can't convey their personality in a written form do write. That, or they are actually super boring in real life.
ReplyDeleteTotally agree - strongly - with every single point... EXCEPT dropping the f-bomb.
ReplyDeleteIt's not that it is unprofessional (which can be a good thing), it is that it makes people less happy, it causes smiles to fade and good moods to dissipate - and excludes the very old and very young.
It might be controversial to say this but you can be witty, original, informative, conversational, informal AND still be nice about it!
You can be "cool" and pack your writing full of content and personality without going trailer trash by being mean and nasty. No harm in being polite. Make your point any way you want - but don't spit in my face to punctuate your sentence.
Swearing only detracts value from any prose.
Just my personal opinion - I acknowledge that the vast majority will disagree and think swearing makes them "more edgy" - but I would propose that doing so illustrates an inability to find more creative methods of adding impact to prose.
You focused on blogs. Any thoughts on papers published in conferences and journals?
ReplyDeletePersonally, I think it's a shame that so much of that knowledge is made difficult to access by adding a lot of formality and sciency-ness (for lack of a better term) to things one could often explain so much better if one didn't try to look like a "real scientist" - at least that's what it feels like most of the time for me.
Contrast the average (useful, worthwhile) paper with the ouput of a less formal, but widely influential author (say, Michael Abrash back in the day).
Or do you think that, assuming quality, there's something to be said for being more formal when the subject is rather advanced?
@Seb Yeah I totally agree with you.
ReplyDeleteIt is necessary to state your work precisely, and conversational exposition is hard to be super precise with. So there is a valid use for the really formal style of academic writing.
*However* that does not mean that the very same paper can't contain informal explanations of the main ideas.
And of course in reality, often the formality is just there to dress up a pig. There are tons of data compression papers that are basically trivial ideas, like "hey binary arithmetic code the bits of the DXT1 interpolators using a context of the neighboring interpolators" , and it takes me hours of trying to figure out their formal language to see that that's all they said.
(it's just like that crazy lawyer language - it does have a purpose in being very precise, but that doesn't mean that you shouldn't still have a hand wavey summary explanation; and of course in reality lawyer language is used to make it seem more serious and formal than it really is, and to keep plebes from understanding)
There are two really bad and really common sins in academic papers :
1. Use of ridiculous formal language, and then still failing to be precise. eg. you'll see data compression papers that start out with a bunch of useless garbage like "S is a source of symbols from the alphabet N which is a field over the integers I and blah blah.." but then they fail to describe in detail exactly how they estimate the escape probability. The point of precise language should be precision of expressing your algorithm, not just making shit look fancy.
2. Inventing your own formal language. This is way way way too common. If there are are any previous papers on similar topics, you need to use their formalism even if you don't like it. If you're reading a bunch of papers in a field, you should be able to learn what the symbols mean and how people express things and it should stay the same from paper to paper.
Nine, nice rant.
ReplyDeleteI would add one point: technical writing should be left to writers. It does not matter if you come to technical as a writer or to writing as a technical (and how is that for an example?)
A lot of what I read was written by people who cannot write themselves out of a paper bag. Even if the paper bag is open, lit, and has red arrows with "This way out" in yellow Arial black painted everywhere.
Normally, I would insert a comment about Dan Brown here...
You have never tagged a technical manual, right? Or you used HTML, right?
ReplyDeleteAs much fun as it is to take your advice and even more fun to read it, it's career suicide.
As for blogs, you call those "writing"? Really?
I find that the best technical writers use the fewest buzzwords. The writers who use the most jargon are those who are writing to impress rather than to inform. If you can't explain a concept without buzzwords then you don't really understand it.
ReplyDeleteReverend Jim
I totally agree with these points:
ReplyDelete1. Use of ridiculous formal language,
2. Inventing your own formal language.
I've seen papers where the authors wasted more lines explaining the formal notation than their contribution. In other papers the formal notation was so ill-defined that the readers needed to guess what the authors meant. Only use formal language if it's going to clarify the text.
What makes most academic papers boring is that there is no narrative structure. I'm able to read hundreds of pages of a nice book in an hour, but some 10 page papers make me feel so sleepy that it takes hours to finish them. And the technical style often removes all personality of the text. If I can't feel that you are excited about your work, why should I care?
You used to be able to find the internal extended versions of some research. Like the great IBM (or AT&T) work of the past, or at some universities, they do internal "technical reports" that are much more informal, and generally much longer, with more discussion and also the crucial missing implementation details. When available, those are almost always vastly superior to the prettied up published versions of the work.
ReplyDeleteAlso, I rather like the books that just take seminal papers in a field and gather them up and publish them. (for example, Sidney Coleman's "Aspects of Symmetry" is one of the greatest field theory books ever, IMO). However, they really could be much better. It would be amazing if they had a 1-2 page introduction to each paper that gave you a conversational summary, as well as a translation into book-wise standard modern notation. Especially when you're gathering up rather old papers (eg. "Key Papers in the Development of Information Theory") there needs to be a translation key like (where they use "S" in this paper we usually use "H" now) etc..
This article is beautiful: I wish more people thought like this, then perhaps half our working lives wouldn't be as fucking tedious as they are. Good for you!
ReplyDeleteUsed to pour over the Borland C manuals. Every on (on each update) had an outrageous pun buried somewhee in the text.
ReplyDeleteTrick was to find the easter egg.
At least the first volume of the Feynman Lectures are all very minorly edited transcripts of lectures (you can get them on tape). The chapters on mathematical background (vector calculus, probability theory, etc) are the driest but even those were nearly unaltered transcripts. It's pretty amazing when you consider how spot on they are; he must have spent forever preparing them.
ReplyDeleteBTW, my one and only criticism of the Feynman Lectures is that their large-scale organization is a disaster. It means that you pretty much have to read them in linear order or you are likely to miss prerequisites or outright gems buried here and there. For example, chapter 27 in volume 2, Field Energy and Momentum, introduces his subscript notation which together with treating grad as a vector makes short work of all vector calculus identities without working in coordinates. Because it's buried in volume 2, which most people haven't read through, this trick of his is virtually unknown.
ReplyDeleteI agree in particular with points #5 and #6. Please talk about something that you could not find an answer for, and had to solve yourself.
ReplyDeleteAnd definitely include the hacks and your thinking behind them.
Here's another thing that I'd like to see, but it's mostly wishful thinking: if someone writes about the solution to a thorny problem, they really should start with a blank slate environment...and I mean blank. That way they'll know exactly what they had to do. I'll wager that a large percentage of articles and blog posts are missing key info, and the authors don't even know it.
its your style :)
ReplyDeletepeople have their respective styles for writing lab report, technical writing and whatsoever.