Allow me a rant on technical documentation. This has been bugging me lately, and I thought I’d lessen the irritation by inflicting it on you. <\/p>\n
The stereotype is that technical people are bad at writing documentation. Technical people are supposedly inept at organizing information, bad at translating technical concepts into plain English, and useless at intuiting what the audience needs to know. There is a reason for this stereotype. It’s completely true. <\/p>\n
From manual pages to tutorials, most prose intended to teach the reader something technical is so poorly written that it might as well be in MD5-hashed Cantonese. People have been emailing me for advice on how to learn X or Y in the field of programming. It’s a bit frustrating, because often there is no decent place to send them for the knowledge they desire. <\/p>\n
Sometimes people say things like, “Ah man. I tried to learn [programming or scripting language] but it was too hard. I’m just not smart enough to figure that stuff out.” But in many cases I think the problem is less with the student and more with the teacher. <\/p>\n
At my day job, I have a primary duty and eleven hundred secondary ones. One of those duties is writing documentation. I do not claim to be a master, but There is a pattern that should be followed when presenting information to a reader. You need to give them an overview of what this document is about so that they don’t waste five minutes reading the thing before they realize they’re on the wrong page. There needs to be a raw presentation of the knowledge (syntax, usage, that sort of thing) and then the in-depth details on the thing, followed by a few working examples. Finally, there should be some links to other related documents in case this isn’t what they were looking for. <\/p>\n
Some of my pet peeves:<\/p>\n
\n1. Assumption that the reader will have prior knowledge of some area not directly related to the tutorial.<\/strong> Under no circumstances should you require the user to have a grip on concepts more complex than the one you’re trying to teach. If you’re explaining how to use gas stove, don’t write directions that include “Step 3: Cook dark chocolate soufflé with raspberry sauce.” <\/p>\n
2. Writing production-quality code to serve as an example.<\/strong> This is probably the result of someone having “good coding practices” beaten into their heads in college. They learn heaps of dogma about what you “never” do when writing code, and apply that thinking to tutorials. If they were asked to provide a working example of an internal combustion engine, their docs would be the blueprints for a Ford F-150 pickup with fuel injection, anti-lock brakes, power steering, and all the other complexities of modern vehicles. It might be a working<\/em> example of an internal combustion engine, but it’s not a useful<\/em> one. It’s much too bloated and complex for the purposes of teaching. A tutorial should be cut down to contain only the concept being demonstrated and the bare minimum of code needed to support it. <\/p>\n
Windows interface programs are really bad at this. I once saw one that was supposed to show you how to implement a simple slider control. The full example was a working sound player that let you browse your computer, open wav files, and start and stop sound playback. It had to interface with special libraries for loading and playing sounds, and had lots of little control buttons to access the various features. All of that, just so it could show you a slider control that was used to govern the volume. (Or panning. I can’t remember now.)<\/p>\n
3. Over-organization of code.<\/strong> It’s really annoying for someone trying to learn to have to track activity over several source files. Perhaps the tutorial is there to demonstrate how to calculate the distance between two points in three-dimensional space. They start at core of the program in main.cpp, which then calls something in distance.cpp, which references vector.cpp, which at last leads them to math.cpp and the four lines of code they care about:<\/p>\n
\nfloat delta_x = x1 - x2;
\nfloat delta_y = y1 - y2;
\nfloat delta_z = z1 - z2;
\nreturn sqrt (delta_x * delta_x + delta_y * delta_y + delta_z * delta_z);
\n<\/code><\/p>\nThanks a lot, pal. Why didn’t you just say so in the first place!?!?<\/em><\/p>\n
I messed around with the DirectX API in the late 90’s, and those example programs suffered from this. Example code should be reduced to the bare number of files possible (one, ideally) and have the minimum level of call depth. You’re trying to teach someone else, not add a shipped title to your resume.<\/p>\n
4. Over-use of jargon.<\/strong> Many, many programming tutorials suffer from this. Supposedly there to introduce newcomers to the discipline, they throw words like “rasterization” and “frustum” at the user without the slightest explanation. The reader will need to know these things, but just tossing out these words instead of paraphrasing in non-technical terms (or taking the time to teach them) simply introduces the question of who exactly is going to read this? Anyone sufficiently knowledgeable to parse the text is likely past the point where they need the tutorial.<\/p>\n
Terrible: Terms are presented without explanation, leaving the user to try to decipher what is being said; turning the whole thing into an exercise in cryptography.<\/p>\n
Acceptable: Terms are defined within the prose, making the text longer and less readable. <\/p>\n
Good: Terms are defined at the start of the document, where they can be skipped or studied as needed. <\/p>\n
Ideal: Terms are presented as hyperlinks to definitions.<\/p>\n
5. Mixing high and low level concepts together.<\/strong> If you’re explaining malloc (), don’t spend three paragraphs talking about memory management and portability issues before you get to the point. If you’re explaining the finer points of memory management, don’t inflict the nitty-gritty details of how to use malloc () on the reader.\n<\/p><\/blockquote>\n
What are the worst docs or tutorials you’ve ever been obliged to read?<\/p>\n","protected":false},"excerpt":{"rendered":"
Allow me a rant on technical documentation. This has been bugging me lately, and I thought I’d lessen the irritation by inflicting it on you. The stereotype is that technical people are bad at writing documentation. Technical people are supposedly inept at organizing information, bad at translating technical concepts into plain English, and useless at […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[66],"tags":[],"class_list":["post-3521","post","type-post","status-publish","format-standard","hentry","category-programming"],"_links":{"self":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts\/3521","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=3521"}],"version-history":[{"count":0,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts\/3521\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=3521"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=3521"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=3521"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}