Example Code

  By Shamus   Jun 1, 2009   57 comments

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 intuiting what the audience needs to know. There is a reason for this stereotype. It’s completely true.

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.

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.

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.

Some of my pet peeves:

1. Assumption that the reader will have prior knowledge of some area not directly related to the tutorial. 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.”

2. Writing production-quality code to serve as an example. 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 example of an internal combustion engine, but it’s not a useful 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.

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

3. Over-organization of code. 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:


float delta_x = x1 - x2;
float delta_y = y1 - y2;
float delta_z = z1 - z2;
return sqrt (delta_x * delta_x + delta_y * delta_y + delta_z * delta_z);

Thanks a lot, pal. Why didn’t you just say so in the first place!?!?

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.

4. Over-use of jargon. 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.

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.

Acceptable: Terms are defined within the prose, making the text longer and less readable.

Good: Terms are defined at the start of the document, where they can be skipped or studied as needed.

Ideal: Terms are presented as hyperlinks to definitions.

5. Mixing high and low level concepts together. 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.

What are the worst docs or tutorials you’ve ever been obliged to read?

20201757 comments. It's getting crowded in here.


  1. Krellen says:

    I’m in user support, so my need to read documentation is less than most IT folk (plus I don’t even learn from tutorials and documentation; I have to do to learn.) However, one of the things that constantly comes up in my performance reviews is the fact that I am very good at explaining complicated technical concepts (like VPNs or the internet in general) in terms that layfolk understand. If I didn’t enjoy getting paid to lurk around on your blog so much, Shamus, I’d probably try to market that skill to other tech-heads.

  2. Eldiran says:

    Oh, that would easily be my school textbooks. I swear, they try to find the most complicated way possible of explaining something (and also fall prey to everything in your post). They are honestly terrible — and this isn’t limited to my programming books.

    These books should be reviewed by someone who knows nothing about the subject — either that, or they should be written by someone who is currently learning the subject and then reviewed by someone who understands it. Then MAYBE they would actually explain the concepts instead of just stating them in a way only experts understand.

    Ah, that does lessen the irritation, doesn’t it?

  3. The Werebear says:

    Most Political Science books are like that too. I don’t know too much about programming or the harder sciences (for exactly the same reasons you listed, actually), but PoliSci is one of the areas where I have to buckle down and slog through it with gritted teeth.

    The difference, I think, is that technical writers put things down like that because that’s all they have been exposed to in terms of how to write such documents. Polisci people, on the other hand, are told to write like this on pain of being ignored as “not obtuse and reader unfriendly enough.” I’m not kidding. I have gotten downgrades on papers because I made my concept too plainly illustrated and understandable.

    Jerks.

  4. Nathon says:

    I don’t remember where it was, but the first tutorial I tried to use for GTK’s Ada wrapper was everything you just said. It failed utterly to explain why anything was done so you just had magic lines of code that made the thing work. I ended up just using the C library reference and the wrapper’s spec files.

    Incidentally, the program I wrote with gtkAda was a sierpinsky triangle maker inspired by you.

  5. Miako says:

    Werebear,

    egads! with the physicists, we generally just write it off as “math is their first language, not English” (Quite true, as most learn math before mastering English)

  6. Martin Annadale says:

    Ok. I know what rasterization is but what the heeeelll is “frustum” ?

  7. Miako says:

    “magic lines of code”… yeah, I remember that, while writing Avisynth plugins. This wasn’t so much because the tutorial sucked, as I was working with someone whose knowledge of “object oriented code” was novice-level, and we just ran off the sample code.

    Not using the tutorial will get you into a lot of trouble, yah? (this wasn’t too bad, actually. numerous well documented examples + one sample made “what do we need to do” rather easy to understand).

    I’ve found the Java swing tutorials to be pointlessly complex. It pains me to say “i like the MS better”… but I really do. That is easy to understand (aka you can just play around and figure it out). Any good java swing tutorials out there?

  8. Robyrt says:

    “This Visio flowchart should provide all the information you need to understand our systems!” Where have I heard THAT one before?

  9. Johan says:

    Hmm, I’m not sure I’m qualified to rate this stuff: I can absorb almost anything if it interests me, but if it doesn’t even the most lucid explanation is too complex. I’m reading a C++ book right now which does a good job of explaining everything, but the end-of-chapter exercises suffer from really ambiguous language, with no sample i/o and no solutions available so you can check if your solution is at least close to what the author had in mind. Though by now I’m starting to like this kind of sink-or-swim approach …

  10. Mik says:

    Ah, yes. This is why I have a job in Technical Publications – translating from one regional dialect of engineerspeak to another! I’ve found that most of my documentation failures are due to a lack of real information about the intended audience.

    A thing to bear in mind is that documentation is not the same as training. A training guide is intended to teach the audience members the skills and facts needed to be experts. The goal of a procedural or reference guide, on the other hand, is very different: it is intended to provide easily-located information that will allow the audience to *act like* experts and perform their functions.

    Don’t forget the most common complaint of technical documentation; ‘nobody tells us anything’. Engineers are too busy producing, support is too frustrated. Sales is too busy making numbers to perform an audience study. Customers feel like nobody listens to what they say, and the writers just feel like they’re specification regurgitators.

  11. Neil says:

    Higher level mathematics textbooks seem to have this problem. It seemed to me that after two semseters of calculus or so, the textbook authors assume that you have a teacher who teaches you the actual concept in simple terms, and the only role of the textbook to provide the explicit mathematical definitions, one example of each, and exercises with final answers in the back of the book. They abandon any attempt at explaining the concept that lies underneath the mathematical process, in favor of providing a rigorous and explicit definition. It becomes more like a manual or a refrence rather than a teaching tool.
    On the other hand, my actual work involves reading aerospace drawings and sepcifications. It is extraordinary the degree to which they try to make things clear. Every page on a drawing has about 30 boxes in standardized locations with standardized information. Drawing #, part #, sheet #, revision level, all the previous revisions, the next assembly up, all the subassemblies that go to this part, all the tolerances, the document rights owners, etc. Every box is labled so you know what it contains. It can be a little hard for people to get used to it at first, but once you do, any engineer or machinist in the US knows exactly where to look to find information about the document.
    I think this is the case because the railroads imposed this as the standard format in the late 19th century. They had nationaly distributed supply chains and contractors, and they had to impose a standard to get the interchangable parts they needed.
    Perhaps computer manuals are so terrible because noone ever had the dominance of the market to impse standard formats?

  12. Been there, done that… from my early days trying to figure out C++ to now, trying to figure out C#/.NET 3.5, the documentation always sucks. I write the code, but I never really understand it, because I don’t fully know the underlying principles sufficiently – and that’s because whenever I see those underlying principles explained, they’re obtuse, self-referential (For the definition of X, see Y. For the definition of Y, see X), or just plain badly written.

    Still, I’ve got a job from faking it, so it can’t be that bad ;)

  13. Joshua says:

    Every piece of programming documentation I’ve ever seen from Microsoft falls into the Clear Only If Known category. If you know what they’re talking about, it can serve as an adequate reminder, but if you’re trying to accomplish something you haven’t done before it’s useless to consult their docs. You’re better off googling and hitting the I feel Lucky button.

  14. Maddie says:

    I’m a technical writer who’s been out of work for nearly five months. My degree is a BA because, 24 years ago when I chose my major, I thought a writer should major in English.

    But quite a few job listings for technical writers specifically ask for a programmer or engineer, or someone with a BS or other technical degree. I assume they do this because they figure that someone with a BA won’t be smart enough to understand their spec documents. This may or may not be true, but it has more to do with the writer’s experience and other education than what their degree is in.

    People who think a BA degree + experience has no value are maybe not the best judges as to whether the technical writing candidate they’re interviewing can explain things clearly enough for the user. If something is second nature to you, then any explanation of it will probably seem adequate.

    My question: would these companies hire BAs in English to do their engineering?

    I’ve also worked with engineers who wrote “drafts” of the manual (jargon-laden things) and were offended when I tried to reword and reorganize so that it would make sense to customers.

    I’ve found software people to be more user-friendly than the hardware engineering types, generally speaking, but maybe that’s just been coincidence. (By “software people,” I mean “makers of software products,” not “programming language textbook writers.” I have a friend who teaches programming, and she doesn’t have anything nice to say about the textbooks she has to work with.)

  15. McGurker says:

    I’m definitely with you on this. I took a CS class this year, learning the very most basic java. Screw modesty, I’m some kind of natural at this shit (prompting 20 people to ask me what so and so means. I said basic people, loops, objects, and arrays. Srsly, dewd.) but every other dang person in my class is hopelessly lost (“What’s indentation?”) and whenever I try to explain things I get a blank stare and end up just telling them what to do. Clearly I’m on the technical person side of the spectrum, ah well.

  16. Hal says:

    Let me throw another log on the “here’s another area just like this” fire. I’m a graduate student in microbiology, and the biological sciences suffer from this immensely.

    We’re told at the start of grad school that text books are utterly worthless. The field moves very quickly, and by the time a text book gets published, much of its content may be incomplete at best or simply wrong at worst. (Though the basics won’t change, it’s often the details that derail you.)

    So, it’s often the case that the best way to learn about a new topic is to peruse review articles on said topic. Those articles often suffer from the exact list you made, Shamus: Unexplained terms, assuming the readers have a certain level of knowledge, complicated selection of examples . . . I could go on.

    The larger problem is that we have a society of “smart” people who know how to absorb information without knowing how to pass it on. They can’t get outside of their own mind and understand what it’s like to not have the same level of information. This is why good teachers are so valuable, and recognizably so.

  17. Vextra says:

    Although I think by now we can probably assume all specialist discpline documentation suffers to a greater or lesser extent from this sort of newbie-unfriendly jargon, nonetheless i feel compelled to share my own hair-pulling favourite: Introduction to Historiography! Or, another favourite, the Nature of Fascism. Unless you spend a minimum of 20 pages tossing around words like ‘public sphere’ and ‘palingenesis’ your not a real post-modern historian. Sometimes I swear using-heck, merely parsing- complicated jargon is a pre-requisite for graduating from higher education. I wonder if its because Academic Publishers pay by the word…

  18. Angie says:

    On the other end of the spectrum, Borland manuals (at least from the mid- to late-eighties) were pretty awesome. I got Borland’s Turbo C around ’87 or so and it came with about thirty pounds of manuals, and amazingly enough you could actually learn to program in C from them. :) They were clear, explained everything, were well organized and used sufficiently simple examples and exercises that someone whose sole previous programming experience was in BASIC [cough] could actually understand what was going on and learn from them. Great stuff.

    Angie

    • Shamus says:

      Angie: I learned on the same books. Probably the same edition. (I was reading the fat stack of Borland Turbo C books in ’90, but they were a couple years old-ish.) I went from BASIC to C using those books.

  19. Daimbert says:

    I find the comments about places that won’t hire anyone without a technical degree for tech writing very funny … my company (at least when I was first applying for jobs 13 years ago) wouldn’t even CONSIDER anyone that didn’t have an Arts degree for Tech Writer positions [grin].

  20. Neil says:

    I notice this now that the “edit” option has timed out, but I really need to put spaces between my paragraphs. Typical engineer, can’t write worth a damn.

  21. Mark says:

    I read most of Fred Brooks’ “The Mythical Man Month” last week. His examples are a bit outdated (it was written in the early 70s), but one of his key insights is how important communication is to the process of software engineering. It pervades the entire experience, from the design to the implementation and, as you note, the documentation. Despite the outdated examples, reading the book has been an exercise in head-slapping for me. It’s a little sad that we haven’t progressed very much since the 70s.

    I don’t have any examples of bad documentation coming to mind, but I will say that when I was exclusively running linux for about half a year, I ran across a few failures of documentation. Also, while I think it’s admirable that linux has a vibrant community willing to answer questions and solve problems for you when you get stuck, some of the responses you get are a little difficult. It’s nice that the command line I got fixed the problem, but I often had no idea what it meant. I spent hours trying to figure this stuff out sometimes…

  22. Spider Dave says:

    I find a lot of my Comp Sci classes have things that are trickier than they need to be. Linked lists is a simple one that comes to mind. Not hard to visualize or implement, but it’s a first year killer because explaining them is difficult.

  23. MOM says:

    I saw Shamus yesterday and I am not surprised today’s post is a rant.

  24. Greg says:

    Sorry to impose my “inferior” scripting language here, but I’m an ActionScripter. My day job is creating Flash content for eLearning courses. Using Adobe’s ActionScript reference library is a cinch. Everything is laid out very nicely per your pet peeves. I know that I can take the examples given in those docs and put them to use with little confusion. I’ve learned C and Visual Basic in school, but so far ActionScript is my favorite, probably because of the immediate results. Its not that I had a bad teacher with either of the other two languages, just that the content didn’t interest me.

  25. OMG, yes! You hit the nail on the head Shamus! My biggest pet peeves are #2, #3 and #5. I can’t tell you how many times I’ve been frustrated by official documentation that gave an intimidating “wall of code” examples. Then I would google the topic and would find a simple 3 line example on some blog and go “Ah! So that how this is done.”

    I also love when the documentation mentions that there are two ways to do something – for example, two ways to call a function foo. There is the easy way, and a complex way reserved for special cases.

    Of course they provide a very detailed example for using the easy case. Then they completely ignore the difficult case or simply make an off-hand cryptic mention that you need to overload certain methods or use a special set of parameters to get the special case working but never show you how it’s done.

    Stuff like that drives me nuts, and I see it all the time.

  26. Captain Kail says:

    Despite having the entire Internet, a strategy guide at my disposal, and this blog I’ve been reading for two years, I am still baffled as to the D&D dice-roll based combat system of Knights of the Old Republic. Does putting a 1d6 crystal into my lightsaber make it stronger than the +1 attack, +1 damage crystal? I may never know.

  27. Deoxy says:

    I’m a programmer, but I’ve been told by at least some people that I do a good job of explaining stuff to lay-people (or at least, that I can, when I take the time), and I have tutored some in the past, and the problem, I think, is that getting complex concepts through to people takes several approaches to get through to even most people – that is, people learn differently, and the more complex and difficult the concept, the harder it is for people to learn it in a way other than the one (or ones) they are good at/prefer. Teaching is its own skill set, but it’s hard to teach something you don’t understand, so good teachers are those smart, gifted, and/or driven enough to be good at teaching AND the subject matter itself. Since many people aren’t even good at one thing, such two-fers are fairly rare.

    That’s at the heart of this, I think. But also…

    -“Technical” writers, as best I can tell, are far too often judged (by their employers) on rigorous, exacting accurateness and/or completeness (possibly for legal reasons for the latter) rather than useful teaching ability.

    -I think many technical types haven’t learned English well, in large part because they weren’t taught well, in large part because they learn differently than most teachers (especially English teachers) – see the above point about different learning types.

    -In my experience, most textbooks are steaming piles of XXXX useless rubish. The best teachers I had were those that used the textbooks for occasional reference on certain topics (where a large block of accurate text would be useful), but otherwise taught us what we needed to know, not what the textbook said. I’m not entirely sure why this is – one would think that the best textbooks would sell better, etc, like most other topics in a free(ish) market… I wonder if the tenure/academic politics crap that makes academia function VERY VERY LITTLE like a free market are some of the problem there?

    out of time…. sigh.

    Edit: OOO – the Mythical Man Month – I’ve been out of school for 10 years, and I still reference that on a regular basis. That, and “The Design of Everyday Things”. If you’re not familiar with that one (called “The Psychology of Everyday Things” in an earlier edition, but it really isn’t psychology), you should really go find a copy. Those are both GREAT books.

  28. HoC says:

    The Adobe Flex documentation. This is the kind of junk you get when you depend on Doxygen to generate your documentation. When I was reading about XML I saw that I could use [n] as an accessor to the children of the XML element, I immediately assumed this was an _index_ based access. I was dead wrong. Apparently this is a reference based access and this caused me major problems when trying to shift the order of children around. (There’s a Adobe JIRA bug you can look up about this is you want more info)

    There are many many other issues. It’s very hard to find a “central” (as in a easily distinguishable place) repository of syntax information and demonstration.

    I feel this can also outright _kill_ a language sometimes. I know the only reason I’m still bothering with flex is partially because it’s the platform we chose to develop on and that I have massive amounts of patience.

  29. I thoroughly recommend the Head First books to anyone looking to learn a new concept (that they cover, obviously.) At first I thought they’d be lacking in content, because of the presentation, but they really do get to the point quickly and effectively.

    I’ve seen far to many bad examples to list them, the vast majority of technical (and non-technical) documentation is badly written.

  30. ngthagg says:

    Neil (#11): Remember that you can’t blame it all on the textbook. Most professors choose which textbook they want to use, so if the book assumes you have a teacher who is teaching you the concepts, that means you have a teacher who assumes that they are teaching you the concepts, even if they aren’t!

  31. Maddie says:

    So, ah, Daimbert… are they hiring??

    Some places will hire different technical writers to write procedures, concepts, and reference material because these three kinds of writing require different (though overlapping) skills.

    Some writers can handle all three and know how to organize them effectively. Sadly, some writers can’t seem to handle any of them, or don’t even realize that they’re different. It’s no fun trying to piece together a procedure out of a long conceptual narrative, or look for important general definitions that are buried in a specific procedure.

  32. Groboclown says:

    For me, probably the oddest book I had was in college, with a book called The Tao of LISP. I can’t even find a reference to it anymore. It essentially listed a set of questions on one side of the page, with an answer on the other side of the page. The whole thing. It was horrible. No index, no useful table of contents.

  33. ClearWater says:

    The stereotype is that technical people are bad at writing documentation. […] There is a reason for this stereotype. It’s completely true.

    Nonsense. It’s because they’re lazy. That’s why we became technical people: so we could (spend weeks or more to) write programs to do the stuff for us.

    Technical people are even too lazy to add the proper text to Java code so that the javadocs app can generate the documentation for them.

  34. Pickly says:

    Ok. I know what rasterization is but what the heeeelll is “frustum” ?

    Those are actual words? (I though the original post was just making up complex sounding words to show how jargon reads to a person new to it. They sure didn’t look like real words.)

    My example: Process control. The book was quite confusing (It was a jumble of new words, followed by some examples, followed by some problems.) The professor teaching wasn’t much better in class from what I’ve heard. I don’t know a single person in that class who understood what was going on, and the only reason I wasn’t worried about failing the class was because it was curved, and no one else seemed to understand it either. i don’t fully understand why the class was so difficult to figure out, but I picked up almost nothing from it.

    (Most other classes were a lot better, I could understand most ideas just by reading a few times, or seeing several examples.)

  35. @Shamus – thank you. I learned something new about 3d graphics today. :)

  36. Duffy says:

    I wholly agree. I have yet to find a reliable and easy to read reference for my general programming needs. It’s amazing how many useless examples live out there in reference land, you would think by now someone would have slapped together a quality/readable reference site. (Hey, that’s not a bad idea, some of us should do something about that…)

    I also vouch for “The Mythical Man Month”, I tend to quote it often, get shot down, and proven correct later. The book is still a great read for software developers, even 30+ years later.

  37. bbot says:

    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.

    Spurious capitalization.

    38 comments and nobody points this out?

  38. Scourge says:

    That stuff reminds me of Math.

    Yes, its strange.

    But seriously, once you get a function like (f o g) o e where you can substitute f, g and e for banana, giraffe and oil or any other words and still get something valid out of it.
    One reason why I hate math now, far to cimplicated with no examples on how to graps it.

    Calculating stuff with a matrix is easy though, even though it is taught after the stuff I mentione dabove. Why?
    Because they use real examples you can understand and grasp.

  39. Dev Null says:

    Interesting. Your intro sounded like you were going to talk about documenting code, but most of your (legitimate and agreed-with) “rant points” seem to have more to do with books about learning programming, or documentation of programming languages, than with the documentation of code itself. I’d do some different things if I was trying to document C++ than if I’m documenting a thing I’d written in it.

    For one thing, program language docs don’t need to have a big picture – goals of the project kind of thing. One of my pet peeves with program docs are the ones that have this section that tells you why you’re here, and then leaps directly to the internal structure of module B. There’s no description of _why_ module B is laid out like that, what alternatives were considered and why they were rejected, or how it relates to modules A and C to actually solve the problem that we started out with.

    Of course, the problem with writing docs that contain all that is that it takes time that you almost never have. I _have_ been given the opportunity by an employer who understood the value, but it often takes nearly as long as writing the code in the first place…

  40. wumpus says:

    Howdy,

    Worst docs or tutorial? That’s easy. ISO/IEC 11172-3, the protocol specification document for MPEG audio coding. It not only suffers from poor writing – which it has in spades – but it also has large sections that were apparently written by non-native English speakers, and other sections that were (according to reliable sources) deliberately obfuscated.

    Between it and the example code (written by a committee of, apparently, graduate students and chimpanzees), one can just barely, sorta produce a working and hopefully canonical audio coder. Given that this is an official document, meant to unambiguously specify an interchange protocol for commercial use, this level of incompetence/monkeywrenching should’ve been legally actionable by somebody.

    (Yes, I did eventually get my coder working – in real time, no less – though the psychoacoustics in the encoder, which are only ‘suggestions’ and not actually part of the spec, never seemed to work very well, probably by design on the part(s) of the intellectual property owners.)

    Alex

    PS – The video spec, BTW, is clear, concise, readable, and authoritative. So it’s not just the nature of the beast.

  41. Carra says:

    It doesn’t really seem to matter anymore in which file the code is. Just use the VS “go to definition” until you hit the code. And if it’s a properly named function such as calculateDistance(x,y,z) there really shouldn’t be any need to look at the code in the first place.

    As for bad documentation, I’m not a fan of microsofts C# documentation. It’s all way too spread, why do they have to split their members, constructors,… Just put it all on one page and put the index on top. Java does a much better job at organizing their documentation.

    As for difficult words and pre knowledge, it’s a bit hard to see how far you can go. Let me take an example from the MSDN website, Array.Sort:
    This method uses the QuickSort algorithm. This is an O(n ^2) operation, where n is the number of elements to sort, with an average of θ(n log n).
    That’s exactly what I would want to know if I look it up. Is it a guaranteed O(n log(n)) algorithm or a quicksort? But it’s not much use if you don’t know what the big O notation means.

  42. SireCh says:

    well, if you think the C# docs from Microsoft are bad, try reading the docs from Mono (the port of .Net to linux). I’ve been working with it for a while, and the documentation is rare, incomplete and sometimes contradictory. And I’ve had this very same problem with other open source projects…

  43. @Carra – you bring up a good point here. This is the sort of useful information that gets very often omitted in API documents. But as per Shamus’ suggestions this probably should not be the first thing you see when you look up that function.

    The first thing you should see is general description of what the method does (sorts an array) and how does it handle different cases. For example, how does it sort objects? Is it smart enough to call the languages explicit or implicit boxing/unboxing methods to extract primitives from their wrappers? What happens when you send in an array with mixed types? You know – practical stuff that you need to know to actually use this function.

    Performance considerations are important but they should probably be below all of that so that it can be looked up when needed, but it does not confuse someone just learning the language.

  44. Colonel Slate says:

    The worst documentation (So far) I’ve ever had the misfortune of reading was a tutorial on how to use a UNIX based system my first year of college. And I knew how to use DOS, so I thought couldn’t be that hard to understand, well, the documentation screwed me good, failed a class due to it actually.

    But I kid you not, at one point in this documentation (goes and finds it) “The user or you can enter information or numbers into the input device using your organ so as to make it go” <- WTF they want me to do? Later I found out that the instructions had been written by a man who’s 4th language was English, and no one had reviewed it, because of missed deadlines. It was bad, real bad.

  45. Nathon says:

    This seems to have devolved into rants on bad documentation, not just tutorials. So I’ll throw in my gripe du jour about Freescale’s reference manuals. Here’s a sample of the stellar English that characterizes these impenetrable tomes: “The user should use in this mode only the ~int output interrupt type (should not use ~cint or ~smi output interrupt types) to read an updated SIVCR.”

    The SIVCR is the register you read to find out how you ended up in your interrupt routine. You don’t read it with an interrupt type, you just read it. Add that nonsense to the already mangled English and you have a manual from the people who now make PPC and 68k chips.

  46. stringycustard says:

    Yeah, I know the feeling of having to research for 30 minutes just to understand some terminology that has nothing to do with what is being discussed in the doc but is “casually referred to”. So joyous.

    Although this isn’t quite the same it was kinda funny when I saw it in my OS coding textbook: a simple concept had code for both Linux and Windows as examples (same concept for each) and the Linux code took up about 25 lines. The Windows code took up close to 4 pages. Really. The Linux version only had one library requirement (for printing to terminal) while the Windows code had multiple library imports of mouse code, buttons, etc.

    I think the problem around how people document is that when they write code they think people want to paste that code somewhere and expect it to work immediately. Like you said, just having the few short lines *about the actual topic* would speed things up tremendously. Although it can be useful occasionally to have fully working code, this could be seperated into 2 parts. Displayed right in the topic would be a simple bit of code (or even pseudo-code) showiing the example without any extraneous calls or includes and then a link could be included for the full working code (or an appendix number for a printed manual).

  47. Zolthanite says:

    Since I’m doing computational math at the moment, my biggest offenders would have to be the following:

    1) CUDA: I appreciate the effort nVidia, but saying “I’m going to assume the non-CS literate people can’t learn basic graphics but can learn a proprietary GPU pipeline specification” is as about as insane as it gets. The very first thing they do is show you the architecture for the G80, as if it’s useful to anyone. It’s technical documentation designed by marketing. I cry.

    That being said, their example code is actually useful. Actually, it’s more useful that the API specification, which is so terse as to be completely useless. Optimizing it, however, is far harder than GPU shaders. Conceptually, I don’t see the point for it existing at the moment.

    2) Intel Math Libraries: For the person who needs to do Fourier Transforms and matrix transformations. I spent three hours trying to figure out what to do to BUILD the thing. The compile flags alone are as bad as library traces through legitimate code. After that, I attempted to find what would be useful functions if I ever got it running. No luck on either. Oh, and no examples that i could find.

    3) Linear Algebra textbooks: It took me 5 years and taking a graduate class on numerical optimization while TAing/sitting in on another undergraduate math class to understand that Lin Alg is actually a really amazing, fundamental field of math. Slightly off-focus, but it’s the one area where people either learn only examples, or have the problems #4, and no one ever tells you what the terms actually mean (#5 would be a welcome addition in many, many academic textbooks at times, since almost nothing is standard in ScienceLand).

  48. Jansolo says:

    The worst tutorial is whichever begins with the “Hello world application”

    I really hate that, because you learn nothing about programming and nothing about the particular language neither. Even more, suddenly you have been involved with the always complicated I/O libraries.

    The second worst documentation is the one within the program. For instance, the javadoc that a programmer is supposed to provide you.

    Sooner or later you will find a “TODO” or a “DOCUMENT ME” comment.

    As Angie said, there is another end of the spectrum. In my opinion, the Java professional books: o’reilly, wrox, manning… has a lot of excellent manuals, tutorials and references, written in a very well explained way.

    I specially love “Thinking in Java”.

    However, they are terrible underestimated because people thinks that the same information could be found across the Internet for free.

    This is one of the worst source of documentation: a tutorial copy-pasted in a blog for anyone.

    And the very worst is the misunderstanding introduced when you don’t put attention to the publish date. For instance, the way a Java program makes an https connection is often coded with inappropriate sentences.

  49. vdgmprgrmr says:

    You know, this very problem has plagued me the last few days.

    I, due to disappointment at non-Rogue roguelikes for being too complex, decided I would make a roguelike of my own. I decided I would try (again) to get into C++. I know some basic C++, so I figured I’d just pick up the curses library and be on with it. So I got PDCurses. And couldn’t find any good examples of code to learn from, or tutorials. Got NCurses. Couldn’t figure out how to START using it. Got TinyCurses. Couldn’t figure out how to get it working (since it relies on SDL). So I gave up, and decided that I should just stop trying, and stick with the slow, fat Blitz3d for all my coding desires.

  50. BlackBloc says:

    The worst documentation in the world is the documentation for the X extension Xrender. That’s because it is technically inexistant, and you get only tidbits of info by looking through the entire Interwebs for tutorials through Google, or by opening up the .h files and trying to parse what the hell they mean.

  51. Ingvar says:

    I have, as they say, a theory. Mostly, people have their technical manual(s) reviewed by people who know the subject matter, intimately. This means they pick up anything “important” that’s missing (and not-well-known enough to be something Everyone Knows).

    It probably also leads to more-than-needed long-winded examples, because in (some) cases, the code that is clear enough to accomplish “teaching” is, in fact, so full of trapdoors that the poor person cribbing the example into production code will, in fact, have flaming death rained upon itself. Of course, now that I try to find a good example, none comes to mind. Oh! Maybe blah = realloc(blah, 4711);. Obvious, usually OK, but occasionally it is leaktastic!

  52. Talrogsmash says:

    my second semester college pascal profesor once said “floating point variables are great because you don’t have to declare them” then proceeded for two weeks to dock people for not using them even though he never showed us how to write one into a line of code. They also weren’t in ther course book.

  53. encryptio says:

    I disagree with the idea that C++ is a good starting place. I find it to be too full of conceptual baggage. I started in the late 90s with C= 64 BASIC, soon moved to REALbasic (at the time, a Visual Basic clone for the mac) and then to Perl and the land of UNIX-likes.

    I think starting with a language in which you can step through every line of code by hand and keep track of it all is the best way to start programming. Languages like BASIC, COBOL, or for the more math-minded, a dialect of Lisp. You might not learn “best practices” or anything directly applicable to real-world programming, but you do learn how to think about programming.

    Seeing as how programming is more akin to the work of an architectural designer rather than a construction worker, I think laying down the good ways to think about programming is far more important than using a full-fledged powerhouse like C++ or Java. Elegance and clarity have been lost on both of those languages, C++ moreso.

    As to worst documentation, this is from a much more advanced standpoint, but the same problem;

    I had been using Darcs (distributed source control system) for a few months with great success, and decided to try Git (another distributed source control system).

    The manpages (prototypical docs for UNIX-likes) for git are terse, but they talk about git at a level of implementors knowledge. They’re so opaque that it’s damned near impossible to learn how to start using git from the manpages. (good manpages can give you a big head start)

    Even though I had months of experience with the concepts behind distributed SC systems with darcs, I found myself googling for the ways to use git to do the same things and finding TONS of blog posts on how to use git, ALL of which were much more helpful than the manpages. Eventually I found gitready, which is a site of categorized, short, and simple tutorials on topics in git usage. They were much more useful.

    Even now, with at least 18 months of heavy git usage, I still use google or gitready rather than the docs that were provided, because I can understand them much easier.

  54. Nathan says:

    Shamus, I found this post very gratifying. I have, from time to time, attempted to learn a programing or scripting language, but have been repeatedly rebuffed when, even the books/courses/etc. that PURPORT to be directed at RANK NEOPHYTES are written with unconscious assumptions about what the reader already knows…

    Even some material I’ve come upon that is, in general, very well written (“Byte of Python”, for example), in that they’re directed at folks who don’t already know any OTHER programing/scripting languages or even basic programing concepts, but ultimately fail (me at least), because…

    …they make assumptions about what is general user knowledge (typically in the form of referencing commands and functions that are likely very basic for the average Linux user, but are completely opaque and esoteric for, say, a Mac OS user).

  55. Jack says:

    Interesting perspectives here. Someone mentioned that teaching is difficult. I can attest to that, as I was a software engineer for 21 years and then became a math/computer science teacher. I did write user documentation when I was a software engineer. Some software companies didn’t want to pay for quality tech writers and editors because, well, it was the software that brought in the sales, not the manuals.

    My wife has been a tech writer since before we were married. She actually learned DEC RUNOFF to write her first computer-generated documentation. She went on to get a Tech Writing Certificate from Northeastern I believe, and was an English major in college. She won an International Tech Writing Award while working at a software company in the Washington, DC area. There are lots of factors that go into writing good technical manuals, and some of you have mentioned these. It’s not easy to do, and the great tech writers are far and few between. Same as programmers.

    Some of you have spoken about the difficulties in learning programming languages from the documentation. I always loved learning programming languages, starting from Dartmouth BASIC on computer with paper tape, to FORTRAN/COBOL/RPG on cards, and many others down the road. I like to start with Hello World, because it is simple and it does show me how to do output and how to compile/interpret and run it. A professor I had in my undergraduate college suggested I always start with a program that adds two numbers, nothing else. Same idea – simple, easy to get syntactically correct, and a sense of accomplishment (albeit small) when I’m done.

Leave a Reply

Comments are moderated and may not be posted immediately. Required fields are marked *

*
*

Thanks for joining the discussion. Be nice, don't post angry, and enjoy yourself. This is supposed to be fun.

You can enclose spoilers in <strike> tags like so:
<strike>Darth Vader is Luke's father!</strike>

You can make things italics like this:
Can you imagine having Darth Vader as your <i>father</i>?

You can make things bold like this:
I'm <b>very</b> glad Darth Vader isn't my father.

You can make links like this:
I'm reading about <a href="http://en.wikipedia.org/wiki/Darth_Vader">Darth Vader</a> on Wikipedia!