Documentation Done Right

« Return to Article
  • Cbuttius 2010-10-05 10:38
    Isn't that what Doxygen is there to do?
  • Rich 2010-10-05 10:39
    (jumps into the scene) "Nobody expects the Source-Code Mismatch!"

    Cue laughter.
  • Anonymous 2010-10-05 10:39
    Judging from the length of today's article you must be a natural at enterprisey documentation...! Just kidding, it was an interesting read and raised a lot of good points but most of this stuff is plain common knowledge. There's no point telling us (ie. the devs on the ground), you're preaching to the converted. Try telling it to our project managers and their bosses, they're the ones who need to hear it.
  • TheCPUWizard 2010-10-05 10:43
    The solution to the Documentation/Code mismatch is trivial (and not, DoxyGen, et.al. do NOT solve it).......

    Wrrite lots of documentation, so much that you neve have time to write code.

    Problem solved!
  • SR 2010-10-05 10:44
    TRWTF is VB
  • Anonymous 2010-10-05 10:46
    SR:
    TRWTF is VB

    Off-topic but painfully true nonetheless.
  • ObiWayneKenobi 2010-10-05 10:49
    I'm a fan of keeping documentation as sparse and succinct as possible to avoid having huge "design documents" or whatnot. For instance, I highly believe in "self-documenting" code that uses very precise variable and method names and making use of whatever commenting mechanism is present in the language (e.g. Javadoc) to highlight the parameters and such.

    I've been using Ruby lately in my spare time so I enjoy the "Ruby Way" of using highly descriptive names so the code is very readable; I've also been using RSpec which can display everything in a readable "document" format as well.
  • Remy Porter 2010-10-05 10:55
    I'm a big fan of literate programming- where the comments are the body of the code file, and the code is on lines specially marked with characters that indicate they're executable. It's really nice- you start with a nice, clear, natural language description of what the program is supposed to do, and then you fill in code blocks around those functional requirements.

    Of course, my experience in enterprise development is that there does not exist a nice, clear, natural language description of what the program is supposed to do. In fact, nobody actually knows what it's supposed to do. I've literally had people hand me a 100,000 line PL/SQL package and say, "It should just do this, but y'know, in this completely different database schema and environment. But it should do what this does."

    "And what does it do?"

    "I don't know. You should probably read it."
  • StupidTheKid 2010-10-05 10:55
    This is pretty much one half of the Agile Manifesto. There are also some popular tools to create automatic documentation, whether from additionnal information in the code (like Doxygen or Javadoc) or with reverse engineering tools able to create class diagrams straight from source code.

    My experience with Doxygen/Javadoc is not favorable unfortunately, as I've seen many comments out of date with the related code. It seems most documentation produced by coders is done reluctantly, and any task done reluctantly seems to be done imperfectly. Oh, the humanity !

    Also, unrealistic deadlines. I've seen good results when time was specifically allocated to create documentation, but this time goes out the window when the deadline looms.
  • Steve The Cynic 2010-10-05 10:56
    The operation of all computer programs can be understood without any documentation.

    I disagree. The program itself is the *definitive* documentation on *what it does*. It may be hard to extract this information from the program, but it is easier than extracting it from out-of-date, incomplete, inaccurate external (external to the program, that is) documentation.

    Therefore you need to qualify this statement with "without any *external* documentation".

    Completeness – a measurement of how in-depth the documentation is; a module-relation diagram is less complete than a class-relation diagram

    Not quite. Completeness also measures how *in-breadth* the documentation is.

    Documentation becomes dangerous (i.e. less than useless) when Perceived Accuracy is greater than actual Accuracy

    *Different*, not *greater*. As Perceived Accuracy becomes significantly *lower* than actual Accuracy, we start to discard accurate information - the perception of inaccuracy causes us to deny reality.

    Of course, Acceptance testing often validates that what sounds good on paper doesn’t work as well in practice

    <shudder magnitude="horrified"/> If you don't find out that it is unworkable until you do Acceptance Testing, you should take up a less intellectual occupation, like staring at walls and sucking your thumb. Small fiddly points like "actually, that would work better if it were a darker blue" don't count here, but major stuff like ar*e-about-t*t workflow should be specked out and validated before deep-fu coding gets started.

    And in general: documents that, as a matter of course, you say should be archived should not be written in the first place, regardless of the documentation standards you have.
  • Ajtacka 2010-10-05 10:56
    But "broil" is a foreign word - at least in most versions of English I know about. The first time I came across it was in US recipes online. I think the translation is "grill".

    Off-topic, but still...
  • So sorry. So very sorry. 2010-10-05 11:02
    I have documentated your design. Pray I don't document it further.
  • Tom7 2010-10-05 11:03
    Alex:
    Verification that their program operates the way they say it does is not one of the first debugging steps; it’s often the last.


    Not nearly cynical enough.
  • Jen 2010-10-05 11:08
    Hello from the third circle of hell! It's a very nice place, actually ;)
  • Tom7 2010-10-05 11:09
    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.
  • Steve The Cynic 2010-10-05 11:09
    ObiWayneKenobi:
    I'm a fan of keeping documentation as sparse and succinct as possible to avoid having huge "design documents" or whatnot. For instance, I highly believe in "self-documenting" code that uses very precise variable and method names and making use of whatever commenting mechanism is present in the language (e.g. Javadoc) to highlight the parameters and such.

    I've been using Ruby lately in my spare time so I enjoy the "Ruby Way" of using highly descriptive names so the code is very readable; I've also been using RSpec which can display everything in a readable "document" format as well.

    Something to think about:

    How do code-level comments (even when kept scrupulously up-to-date with changes in the code) show you a top-level view of the architectural structure and so on of the program/system?

    Ponder the value of an analogy between reading code-level comments as an aid to understanding the *whole* system, and looking at individual grains of sand as an aid to understanding the shape of Waikiki Beach.
  • TheJasper 2010-10-05 11:09
    Steve The Cynic:

    And in general: documents that, as a matter of course, you say should be archived should not be written in the first place, regardless of the documentation standards you have.


    mostly true but you are ignoring two things. The side effects of writing documentation and accountability.

    Writing documentation can just be a way of putting your thoughts in order. Though archiving it may not be necessary in this case.

    Accountability is important too, depending on the project. For projects which have a chance of killing people with a bug I would definitely go all out on documentation. If you ever need it you probably killed someone but not having means you will be held accountable.

    In general I am in favor of you viewpoint. If you do UML, write the UML you need not every possible diagram. Also maintain it. If documentation needs to be written it needs to be maintained.

    I dislike the Agile wording on documentation because it gives an excuse to lazy developers to not write documentation. This is not what they are saying but it is the message some people are getting.

  • Remy Porter 2010-10-05 11:13
    Ajtacka:
    But "broil" is a foreign word - at least in most versions of English I know about. The first time I came across it was in US recipes online. I think the translation is "grill".

    Off-topic, but still...


    Broiling is not like grilling. It's cooking food under a very high heat and very close to the heating element. Most ovens in the US come equipped with broilers or a broiler setting. For example, in my electric oven, if I want to broil something, I move the rack as close as possible to the top heating element and turn on the broil mode.

    Broiling is often a substitute for grilling, though. Like, it's 50º and rainy out today. I'm not going to grill a steak- but I might broil it for a few minutes on each side to get the outside well sealed and leave the inside rare.
  • TheJasper 2010-10-05 11:18
    Steve The Cynic:

    Something to think about:

    How do code-level comments (even when kept scrupulously up-to-date with changes in the code) show you a top-level view of the architectural structure and so on of the program/system?

    Ponder the value of an analogy between reading code-level comments as an aid to understanding the *whole* system, and looking at individual grains of sand as an aid to understanding the shape of Waikiki Beach.


    If you have written your code well then your analogy doesn't hold. My toplevel clearly shows I have started my application loop. This tells me I am doing the application thing. Later on I see that I am performing a MajorBusinessProcess. No grains of sand there. At some point I'll reach a put this number in that variable code, that is your grain of sand.

    If you just start reading in the middle of the code everything may seem like a grain of sand. You don't start a book in the middle either.

    I dislike comments in code. Javadoc or something like it isn't so awful, but comments in the code itself probably mean you should've written that code better. I especially can't stand apologetic comments where the developer tries to weasel out of being responsible for writing bad code.

    Anyway, code is only going to get you so far. That's why we also have UML, requirements, plain text, use cases, stories, <insert your favorite form of documentation>, etc.
  • Chris Cowdery 2010-10-05 11:21
    You will find me poring over my code, not pouring.....

    Chris.
  • toth 2010-10-05 11:23
    I disagree about database documentation. I've recently been burned by a particularly arcane database structure that took headache-inducing analyses of some database tables. Something like "Domain object X is a package which contains elements that are either other packages or individual components, oh but a top-level package is actually a 'version' of the object, oh and while the structure can be nested arbitrarily deep, it's actually only ever used to one level (i.e. 'version' package->(component package)->(component or package)->component". What I wouldn't have given for some sort of a description of that structure.

    Granted, it wouldn't have to have been explicitly a database documentation, I would have been just as happy with a documentation like "OK, so we have packages, and they can contain packages or components,etc.".
  • RandomUser423695 2010-10-05 11:26
    Ajtacka:
    I think the translation is "grill".
    A quick dictionary check suggests "grill" is a specific form of "broiling". To broil is to expose the object to direct radiant heat regardless of source or position, while grilling (generally) requires a grill or griddle with the object (usually) above the heat source.
  • CLANDRESS 2010-10-05 11:27
    I'm working with a system written in the late 80's. What we really need is documentation of what the business does. It's easy to see what the program does but what does the business actually need it to do?
  • MLD 2010-10-05 11:32
    Hmmm. Your description of "broiling" in the US sounds exactly like "grilling" in the UK.

    So what is "grilling" in the US? Something you only do outside, like "barbecuing" in the UK...?
  • TheJasper 2010-10-05 11:33
    Chris Cowdery:
    You will find me poring over my code, not pouring.....

    Chris.


    you'll sometimes find me pouting over code...
  • bob 2010-10-05 11:36
    "No amount of documentation will help the average developer understand brilliant systems..."


    The *real* WTF is that you misspelled "brillant."
  • SeySayux 2010-10-05 11:39
    Conclusion: either accurracy or percieved accuracy need to be less than one.

    Unless, of course, these are measured procentually on a scale from zero to one.

    (If you don't get this, do the math ;) )
  • Otto 2010-10-05 11:41
    UML? People actually use that in the real world?

    Nah, they don't. We know this.
  • Anonymous Coward 2010-10-05 11:43
    Tom7:
    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.

    Instead of fairy tales, you'd be better off checking a dictionary:

    http://www.merriam-webster.com/dictionary/broil

  • Mr. Can't bother to register 2010-10-05 11:49
    Steve The Cynic:
    The operation of all computer programs can be understood without any documentation.

    I disagree. The program itself is the *definitive* documentation on *what it does*. It may be hard to extract this information from the program, but it is easier than extracting it from out-of-date, incomplete, inaccurate external (external to the program, that is) documentation.

    Therefore you need to qualify this statement with "without any *external* documentation".


    I don't see how your points differ from Alex' points?

    Steve The Cynic:

    Completeness – a measurement of how in-depth the documentation is; a module-relation diagram is less complete than a class-relation diagram

    Not quite. Completeness also measures how *in-breadth* the documentation is.


    Huh?

    Steve The Cynic:

    Documentation becomes dangerous (i.e. less than useless) when Perceived Accuracy is greater than actual Accuracy

    *Different*, not *greater*. As Perceived Accuracy becomes significantly *lower* than actual Accuracy, we start to discard accurate information - the perception of inaccuracy causes us to deny reality.


    Which is exactly why it then becomes *useless*, not *dangerous*. *Dangerous* documentation is documentation that increases the risk of misinterpretation. Documentation that you don't trust can't do that.

    Steve The Cynic:

    Of course, Acceptance testing often validates that what sounds good on paper doesn’t work as well in practice

    <shudder magnitude="horrified"/> If you don't find out that it is unworkable until you do Acceptance Testing, you should take up a less intellectual occupation, like staring at walls and sucking your thumb. Small fiddly points like "actually, that would work better if it were a darker blue" don't count here, but major stuff like ar*e-about-t*t workflow should be specked out and validated before deep-fu coding gets started.

    And in general: documents that, as a matter of course, you say should be archived should not be written in the first place, regardless of the documentation standards you have.


    It's not always easy to figure out what the user actually wants until you give him a prototype to fiddle with.
    And archived documentation can be valuable when it comes to showing how exactly the application was originally inteded to be.
  • The Enterpriser 2010-10-05 12:10
    I read this, enjoyed it and agreed with it for the most part, however it felt more like evidence which was building up to some great solution/conclusion. Then it ended.

    What is the point of the article? That we should design systems to be understandable? Is an 1800 word essay really necessary to come to that conclusion?

    Also, it seems that this article is referring to documentation written by developers with the target audience being other developers who might need to maintain/extend the system in the future. I'm not so sure that the same arguments all apply for documentation written for different audiences - e.g. the team who has to support the application
  • Cbuttius 2010-10-05 12:10
    Otto:
    UML? People actually use that in the real world?

    Nah, they don't. We know this.

    Usually as an afterthought.

    CASE tools, well Rational Rose in particular, suffered the issue of being overpriced, far too high for most companies, and design in theory is rarely applicable in practise.

    Actually the C++ FAQ discusses in depth why a circle is not a type of ellipse in OO. Although actually a read-only circle is a type of read-only ellipse, it's just once you allow an interface to modify an ellipse, you can't always run it on circles.

    Most of the time you don't end up with the perfectly designed OO solution but a practical one that works, and sometimes is even easier to maintain than the perfect one.

  • PotatoEngineer 2010-10-05 12:11
    TheJasper:
    ...
    Ponder the value of an analogy between reading code-level comments as an aid to understanding the *whole* system, and looking at individual grains of sand as an aid to understanding the shape of Waikiki Beach.


    If you have written your code well then your analogy doesn't hold. My toplevel clearly shows I have started my application loop. This tells me I am doing the application thing. Later on I see that I am performing a MajorBusinessProcess. No grains of sand there. At some point I'll reach a put this number in that variable code, that is your grain of sand.
    Except that even top-level code contains the odd grains of sand, which are much like noise to people trying to get the high-level view of what's going on.
    ...

    I dislike comments in code. Javadoc or something like it isn't so awful, but comments in the code itself probably mean you should've written that code better. (...)[\quote]Wait, what? The code is going to tell you what is happening, but it's rare for the code to tell you why you did it that way, or why <the other three things you tried> aren't good ideas, even though they look that way at first.
  • Zylon 2010-10-05 12:12
    MLD:
    Hmmm. Your description of "broiling" in the US sounds exactly like "grilling" in the UK.

    So what is "grilling" in the US? Something you only do outside, like "barbecuing" in the UK...?

    Silly rabbit, everyone knows they boil everything in the UK.

    Grilling is fast cooking with high heat. Barbecue is slow cooking (the slower the better) with low heat. Many people incorrectly use the word barbecue to refer to grilling.

    Broiling is just grilling (or baking) with the heat applied from above.
  • David 2010-10-05 12:13
    What I've found most necessary is Interface Documentation.
    Two examples:

    1 - BIG development for a new Telco, several different systems which had to talk to each other but didn't. No progress: each team waiting for the other to fix things. I persuaded Snr Manager to instruct me to hold design reviews, at which I required the teams' designers to document their system interfaces, then we reviewed them together. That's when we started to find that system A sent 1 for Enable and B expected 1 for Suspend, and that some required values were not set up at all.

    2 - One man project (me) for small company, processing data for its customers. Our marketing/sales manager send data spec to new customer, who generated data that would not load into our system. Once I got a copy from him, I realised that he'd sent them the SQL table definition with no explanation of what format to put the data in! Soon fixed by adding explanation of some key fields plus defining the file format.

    Also - I was influenced by Literate Programming many years ago, and always add comments to my code. The person who usually benefits from my explanations of how it works and why I did it this way is ... me when I have to change it later.

    Sometimes I even comment test code I'm about to use and delete ;-)
  • Anonymous 2010-10-05 12:15
    Design documentation is outside of my remit but I do my bit at the code level by enforcing code commenting standards throughout my company. I have Sandcastle set up to generate MSDN-style HTML pages for every code file in our codebase. This gets executed as part of our nightly automated builds and the output gets dumped onto a central server. This means that everyone in the company is just a hyperlink away from an up-to-date specification of the entire codebase.

    I have to admit that this only works because I'm so aggressive at getting people to follow the commenting standards (that I wrote). They know I review the comment coverage every week and will raise PRs for them to update any code that is not perfectly commented. We don't even do formal reviews of the actual code but I still review the comments evey week to make sure they are up to scratch. Very often, the comments are better written than the actual code.

    Despite all this, I'm pretty sure nobody reads the generated HTML spec except me. But as they say, you can lead a horse to water...
  • Steve The Cynic 2010-10-05 12:16
    Mr. Can't bother to register:
    Steve The Cynic:
    The operation of all computer programs can be understood without any documentation.

    I disagree. The program itself is the *definitive* documentation on *what it does*. It may be hard to extract this information from the program, but it is easier than extracting it from out-of-date, incomplete, inaccurate external (external to the program, that is) documentation.

    Therefore you need to qualify this statement with "without any *external* documentation".


    I don't see how your points differ from Alex' points?


    Alex said (paraphrased) that you can do it with no documentation, (by implication) **not even the program**.

    Mr. Can't bother to register:
    Steve The Cynic:

    Completeness – a measurement of how in-depth the documentation is; a module-relation diagram is less complete than a class-relation diagram

    Not quite. Completeness also measures how *in-breadth* the documentation is.


    Huh?


    Imagine the system as a collection of stacks of "stuff" (modules, classes, etc., depending on how you slice it for your document).

    "In-depth" measures how far you go down the stacks.

    "In-breadth" measures what fraction of the stacks you cover, and is arguably a more useful measure of completeness.

    Mr. Can't bother to register:
    Steve The Cynic:

    Documentation becomes dangerous (i.e. less than useless) when Perceived Accuracy is greater than actual Accuracy

    *Different*, not *greater*. As Perceived Accuracy becomes significantly *lower* than actual Accuracy, we start to discard accurate information - the perception of inaccuracy causes us to deny reality.


    Which is exactly why it then becomes *useless*, not *dangerous*. *Dangerous* documentation is documentation that increases the risk of misinterpretation. Documentation that you don't trust can't do that.


    True-but-not-trusted documents *can* be dangerous. Suppose that I read a piece of documentation that (truthfully) says that there is a lethal radiation hazard in the next room, and further suppose that I am do not believe the documentation at all. I will leave my hazard suit behind when I go in the room, and I will die.

    An extreme example, sure, but it illustrates the point that if the documentation is not trusted, then I may make false assumptions that something else is true when in fact that alternative is not true.

    Mr. Can't bother to register:
    Steve The Cynic:

    Of course, Acceptance testing often validates that what sounds good on paper doesn’t work as well in practice

    <shudder magnitude="horrified"/> If you don't find out that it is unworkable until you do Acceptance Testing, you should take up a less intellectual occupation, like staring at walls and sucking your thumb. Small fiddly points like "actually, that would work better if it were a darker blue" don't count here, but major stuff like ar*e-about-t*t workflow should be specked out and validated before deep-fu coding gets started.

    And in general: documents that, as a matter of course, you say should be archived should not be written in the first place, regardless of the documentation standards you have.


    It's not always easy to figure out what the user actually wants until you give him a prototype to fiddle with.

    I believe that this is more or less what I said. Acceptance Testing is the final test at the end of the *final* delivery cycle. This is the very worst time possible to discover fundamental flaws. "Specked out and validated" implies "give him a prototype to fiddle with".

    Mr. Can't bother to register:
    And archived documentation can be valuable when it comes to showing how exactly the application was originally inteded to be.


    "What they asked for" is not the same thing as "what they wanted". And Alex's definition for "to be archived" was dangerously close to "will never ever be read again". Write-once-read-never documents should not be written. Design documents should not be read-never. At the very least, you should be able to validate implementation against them.
  • bob 2010-10-05 12:18
    I don't think you can really get away with calling words foreign just because you don't recognise them.

    Broil is a great word because its etymology is often specified in such a way as to summarise 100s of years of conflict:
    . Old French - bruir - to burn
    . Middle English - brulen - to cook
  • Jay 2010-10-05 12:21
    Chris Cowdery:
    You will find me poring over my code, not pouring.....


    We have lots of code here that I'd like to pour over. Gasoline, usually.
  • frits 2010-10-05 12:21
    You should see the finger pointing from CM at my job if some documentation is found to be innacurate. Of course they can only catch stuff related to build procedures and such. The technical details could be completely wrong and they would never know.

    BTW- I always think of flat screw heads as looking like this: (|)
  • cdosrun 2010-10-05 12:27
    MLD:
    Hmmm. Your description of "broiling" in the US sounds exactly like "grilling" in the UK.

    So what is "grilling" in the US? Something you only do outside, like "barbecuing" in the UK...?


    In my area of the US, grilling is something you do outside, over a fire. It's not the same as barbecue. You place the meat on a wire rack, or grill, that is placed over the fire. The fire may then be covered or left uncovered, depending on the style of grilling and the meat. The heat is relatively high, and the cooking time is relatively short.

    Barbecue, on the other hand, generally has a lower heat and a longer cook time. It's usually pork, and usually flavored in one of a few roughly similar ways- The "right" way being a hotly contested belief. A spit is often used, but not required.

    The only exception I can think of would be a grilled cheese sandwich.

    People in other areas of the US, or people who look up formal definitions in the dictionary, may have different ideas- but that's what I mean if I invite my neighbor over because I'm grilling some steaks.
  • Jeremy 2010-10-05 12:30
    I'm amused that you picked a 2x4 as an "obvious" example. It is not obvious to someone who has never worked with wood before that a 2x4 is not actually 2" by 4", but 1.5" by 3.5". So much for idiot-proof specifications.
  • Jay 2010-10-05 12:32
    I used to work for ... well, I probably shouldn't name the organization, but let's just say they're a branch of the U.S. military that specializes in air combat.

    We used to get tons of forms we were supposed to fill out that had a lot of overlap in the information requested. So someone got the idea of consolidating all these forms into one big form and put it on a web site. Great idea. Except ... they didn't really eliminate the redundant questions. So we'd have a question like, "What functions does this system perform?". A little later would be, "What are the requirements for this system?" And then further on, "Explain the capabilities provided by this project."

    Even questions that required one-word, unambiguous answers would be phrased in different ways. Like, they had a policy that all systems must be converted to web applications (a crazy policy in itself, but that's another story), so there was a question, "On what date will this system be migrated to a web app?" A little later, "Date on which this system will be web-enabled". And later still, "When will the system be on the web?"

    I took to cutting and pasting my answers. Occasionally I thought it would be fun to give totally different answers when they asked the same question twice. Like when they ask for the requirements, talk about managing stock in the warehouses, but when they ask for capabilities, say that it tracks employee sick days. See if anyone notices. But I was too much of a coward, it would have been funny but I didn't want to get fired over it.
  • Jay 2010-10-05 12:34
    I don't know if less planning on your 2x4's is really a good idea. Surely we should always do good planning on carpentry products. If you cut a board wrong, you have to throw it away and get another. I think you meant "less planing".
  • Mike 2010-10-05 12:35
    MLD:
    Hmmm. Your description of "broiling" in the US sounds exactly like "grilling" in the UK.

    So what is "grilling" in the US? Something you only do outside, like "barbecuing" in the UK...?


    I'm a bit of a barbecue snob, and grilling is not the same as barbecue.

    Broiling is cooking, usually indoors in an oven, at high radiant heat with the food placed close to the heating element.

    Grilling is cooking, usually outdoors, over direct heat, usually provided by gas burners or charcoal.

    Barbecue is cooking meat over a long period of time at relatively low heat. Pit barbecues can hold hundreds of pounds of meat and can take up to 8 hours to cook. Low and slow.
  • davedavenotdavemaybedave 2010-10-05 12:38
    To me the most important line in any piece of documentation, and one that's usually missing is the one that says: "This document correct as-of [Date last updated]".
  • frits 2010-10-05 12:41
    davedavenotdavemaybedave:
    To me the most important line in any piece of documentation, and one that's usually missing is the one that says: "This document correct as-of [Date last updated]".


    Do you mean the only line I change when releasing a new version?
  • Kyle H 2010-10-05 12:44
    My two cents is that the "write-only" documentation is mostly for outside contractors and new hires.

    I always try to design my documentation for my successor, not my peers. I want him to understand why this value is hardcoded, what servers this process touches, how this process works in context of the whole enterprise, etc.

    And yes, when you give your 2 weeks notice, you should spend your time updating all of that documentation to hand over to your successor, and leave them ready to jump in as quickly as possible.
  • Edward von Emacs, VI 2010-10-05 12:46
    Rich:
    (jumps into the scene) "Nobody expects the Source-Code Mismatch!"


    Our chief weapon is surprise, surprise and fear...

    Sounds about right!
  • Jay 2010-10-05 12:49
    Something you perhaps imply but that is often ignored is that documentation can serve three very different purposes:

    1. Communicate information between members of the project team during the course of the project.

    2. Record information about the project for future reference. This could mean to people who were not involved in the project when it was developed, or to people who were involved who are coming back at a later time and may not remember.

    3. Help someone to formulate his thoughts.

    For example, probably the most important purpose of a requirements paper is #1: To communicate the requirements for this project from the users to the developers.

    A users manual is primarily for #2. It should describe how to use the system for people who come along in the future.

    A class diagram or entity-relationship diagram's main purpose might be to help the person writing it get his thought in order. I often draw ERDs, for example, that I know no one else will ever look at, just to help myself get it all together.

    Of course documents can serve more than one of the above purposes.

    Once stated that way, it's obvious that type 2 documents must be carefully preserved and kept current, while type 1 and 3 need not be. Indeed on type 3 documents, I often scribble ERDs or data flow diagrams on a piece of paper just to work out what I need, and then promptly throw them away once I've created the database or whatever.

    One of the biggest time-wasters in many organizations I've worked in is the requirement that documents be kept updated after their useful life has ended. I've had many times when I was required to update a systems design document after programming was complete to reflect any changes made in the course of development, when I knew full well that now that development was complete, no one was ever going to look at these documents again. It reminds me of the joke of the aspring writer who is told by a publisher, "Your submissions are so bad, we have to rewrite them before we throw them away." Why update something just before filing it in the Black Hole Archive?
  • mainframe_guy 2010-10-05 13:05

    Best part of the article:

    The ease of extracting and understanding these specifications varies on the complexity of the subject at hand.

    * A 8’ length of 2” x 4” is just that, less planning

    And this sums up the end problem. A two-by-four isn't actually 2" by 4". Hence, there is still ambiguity in the sentence above. This is the proof that documentation (less is more) is hard to write.

    For the record, I work in a gigantic company. We have almost zero documentation due to Agile PMO with a horde of professional coders imported by tier one outsourcing firm. These guys work HARD to make their sprint dates. They have troubling reading the existing code, have little UML literacy skill and sometimes don't understand the problem (eg a stopped check can only be stopped once)... and none of that matters because documentation is the first item cut when faced with the sprint deadline.

    The best solution we have right now, create very coloful and fancy looking powerpoints to describe architecture and implementation detail. Those work great in the 20+ person daily meetings.

    As for the comment about old documentation perceived as inaccurate. I agree with that. However some of the best documentents I have seen are from the 1970-80s regarding how the ACP Airline Control System assembler systems run today's ATM network.
  • ais523 2010-10-05 13:06
    Rich:
    (jumps into the scene) "Nobody expects the Source-Code Mismatch!"

    Cue laughter.

    One of the projects I maintain actually has a test-case for that one. It even triggers sometimes. (Nearly always, because a file's being used but nobody remembered to check it in.) Probably more projects should test for that automatically...
  • Edudbor 2010-10-05 13:44
    Here's my theory on Documentation and it extends right into software development approaches as well. Particular agile/iterative stuff that seems to be so popular right now.

    The problem isn't the process we use to create these things. The problem is that a lot of us *suck*.

    See, the types of people who sit down and spend large amounts of time trying to make the process better; those are people who don't suck. In fact, they are normally in the 1% of their peers; certainly the top 10%.

    "We do waterfall - and look how bad our code/product is"
    "Our documentation process sucks! Look how bad it is!"

    You get a team of like-minded, hot-shot people who want to make a better process and they come up with something new. And they say, 'Look how much better this is!'

    And there stuff - created by the top 1% is way better than the typical crap you see in applications written by the general population of programmers.

    And then, you get the early adopters. Again - these are people who are actively looking for ways to do things better. They are motivated and knowledgeable and they stumble across some new approach and decide to adopt it.

    These early adopters are also, at the top of their game. Maybe not top 1% - but top 10-15%. They see how awesome the amazing guys are doing with it, learn it, and become advocates of it at their office/work place - where they are held in high regard (because they are good at what they do).

    Eventually, it trickles down. Down to the below average, crappy folk. By this time, it's mandated by company policy. 'You must document like this' 'We are an agile shop now, you have to do it this way'.

    These devs don't care. They don't want to learn something new. And even though you've moved them onto something new; they don't do it right, and just generally suck. And once they are on-board; your project failure rate goes sky-high, just like we saw with the old approach.....until someone comes up with something new.

    Good documenters will produce good documentation.
    Bad documenters will not.

    You can argue all day about what 'documentation style' is the best. But it doesn't matter.

  • Jason Martens 2010-10-05 13:55
    Actually, an eight foot 2x4 is 3 1/2 inches wide by 1 1/2 inches thick. Go figure.
  • Anonymous Brave 2010-10-05 14:04
    With this nonWTF I did as I do with most documentation... tl;dr
  • imgx64 2010-10-05 14:06
    TRWTF is that TDWTF turned into a programmer's blog. I read the whole bloody thing waiting for the punchline. *sigh*
  • Bert Glanstron 2010-10-05 14:21
    imgx64:
    TRWTF is that TDWTF turned into a programmer's blog. I read the whole bloody thing waiting for the punchline. *sigh*

    Dear imgx64,

    In case you can’t tell, this is a grown-up place. The
    fact that you insist on everything being a joke
    clearly shows that you’re too young and too stupid
    to be using thedailywtf.com.

    Go away and grow up.

    Sincerely,
    Bert Glanstron
  • Some dude 2010-10-05 14:23
    imgx64:
    TRWTF is that TDWTF turned into a programmer's blog. I read the whole bloody thing waiting for the punchline. *sigh*
    The article type was "Alex's Soapbox"-- it was intended to read like a programmer's blog. Alex occasionally likes to pontificate.
  • Moshe 2010-10-05 14:25
    The operation of all computer programs can be understood without any documentation.


    This statement is incomplete. What a computer program does can be understood without any documentation. But that is not necessarily true about the Why.

    The Why question is what problems the code was trying to avoid, what assumptions it made on its environment, on the inputs that it gets, on the quality of surrounding modules, etc.

    I won't get into an argument if the word operation include only the what or also the why, but I think that it is quite obvious that if you want to change a code you should know the why as well as the what.

    The implication IMHO are clear: Documentation about the Why is in many cases net-new information that doesn't appear as part of the machine readable code. So it take precedence over documenting the What.
  • charles 2010-10-05 14:25
    Mike:
    MLD:
    Hmmm. Your description of "broiling" in the US sounds exactly like "grilling" in the UK.

    So what is "grilling" in the US? Something you only do outside, like "barbecuing" in the UK...?


    I'm a bit of a barbecue snob, and grilling is not the same as barbecue.

    Broiling is cooking, usually indoors in an oven, at high radiant heat with the food placed close to the heating element.

    Grilling is cooking, usually outdoors, over direct heat, usually provided by gas burners or charcoal.

    Barbecue is cooking meat over a long period of time at relatively low heat. Pit barbecues can hold hundreds of pounds of meat and can take up to 8 hours to cook. Low and slow.


    So let's clear up some regional dialects.

    As far as I understand... and I might be wrong...

    UK says:
    1. Broiling means you're not from around here.
    2. Grilling means cooking in the oven under the flame/heating element.
    3. Barbecuing means cooking (usu. outdoors) over a fire, sometimes with hickory or other wood chips for flavor.

    The Southern/Southwestern US says:
    1. Broiling means cooking in the oven under the flame/heating element.
    2. Grilling means cooking (usu. outdoors) over a fire, sometimes with hickory or other wood chips for flavor.
    3. Barbecuing means cooking (usu. outdoors) over low heat usu. with lots of smoke, sometimes with hickory or other wood chips for flavor. It can also mean cooking meat on a spit.
    4. Rotisserie isn't in my language.


    The Northeast US says:
    1. Broiling means cooking in the oven under the flame/heating element.
    2. Grilling means cooking (usu. outdoors) over a fire, sometimes with hickory or other wood chips for flavor.
    3. Barbecuing means cooking (usu. outdoors) over a fire, sometimes with hickory or other wood chips for flavor.
    4. Rotisserie means cooking meat on a spit

    See http://en.wikipedia.org/wiki/Grilling#Regional_variations
  • Head of the clbutt 2010-10-05 14:29
    David:
    What I've found most necessary is Interface Documentation.
    Two examples:

    1 - BIG development for a new Telco, several different systems which had to talk to each other but didn't. No progress: each team waiting for the other to fix things. I persuaded Snr Manager to instruct me to hold design reviews, at which I required the teams' designers to document their system interfaces, then we reviewed them together. That's when we started to find that system A sent 1 for Enable and B expected 1 for Suspend, and that some required values were not set up at all.

    2 - One man project (me) for small company, processing data for its customers. Our marketing/sales manager send data spec to new customer, who generated data that would not load into our system. Once I got a copy from him, I realised that he'd sent them the SQL table definition with no explanation of what format to put the data in! Soon fixed by adding explanation of some key fields plus defining the file format.
    +1
  • Toster 2010-10-05 14:31
    Steve The Cynic:
    The operation of all computer programs can be understood without any documentation.

    I disagree. The program itself is the *definitive* documentation on *what it does*. It may be hard to extract this information from the program, but it is easier than extracting it from out-of-date, incomplete, inaccurate external (external to the program, that is) documentation.


    Er.. shouldn't the documentation.. like.. also contain what the program is meant to do? I mean TDWTF is a great source of code we can read but can't possibly understand what it should be doing.
  • Gator BBQ 2010-10-05 14:47
    I've always felt the code was the documentation, so I keep the variables short to make it more readable (just start with 'a' and work your way down the alphabet). I also keep the method names short and consistent to help with comprehension, 'm1', 'm2' etc.

    Any sql should be inline so the developer who follows you doesn't have to go digging around to find what it does. It should be right there in the same class file.

    Finally, abstraction = confusion. Don't wrap all your code up and hide it...state it plainly and clearly. Plus it is easier to copy and paste into other areas of the code when you don't have it hidden in methods or, even worse, services.
  • Croc BBQ 2010-10-05 15:00
    Gator BBQ:
    I've always felt the code was the documentation, so I keep the variables short to make it more readable (just start with 'a' and work your way down the alphabet). I also keep the method names short and consistent to help with comprehension, 'm1', 'm2' etc.

    Any sql should be inline so the developer who follows you doesn't have to go digging around to find what it does. It should be right there in the same class file.

    Finally, abstraction = confusion. Don't wrap all your code up and hide it...state it plainly and clearly. Plus it is easier to copy and paste into other areas of the code when you don't have it hidden in methods or, even worse, services.

    I hear you and agree completely. I also think it's confusing when you use letters that don't resemble numbers. For example, here's how I would print a list of characters (in Java):

    int l1 = list1.length();
    int l2 = list2.length();
    boolean I = true;
    for (int O = 0; ; O++)
    {
    if (!I || O >= l1 || O >= l2) {
    break;
    }
    System.out.println(list1.get(0).equals(list2.get(0)) ? "==" : "!=");
    list1.remove(0);
    list2.remove(0);
    }
  • foobar 2010-10-05 15:10
    Just a suggestion, you should read what you wrote ;)
    (just pointing out there's bit of redundancy in that, and not much of the useful kind..)
  • History Teacher 2010-10-05 15:26
    A 8’ length of 2” x 4” is just that, less planning

    You obviously don't know very much about lumber if you say that... There are different 2-by-4.

    Though I admit, with lumber you can usually just over-design instead of having calculated-to-be-correct plans, and still have decent result, only with a bit higher cost than is necessary. But with SW development, over-design usually leads to a WTF.
  • nonpartisan 2010-10-05 15:39
    Steve The Cynic:

    True-but-not-trusted documents *can* be dangerous. Suppose that I read a piece of documentation that (truthfully) says that there is a lethal radiation hazard in the next room, and further suppose that I am do not believe the documentation at all. I will leave my hazard suit behind when I go in the room, and I will die.

    An extreme example, sure, but it illustrates the point that if the documentation is not trusted, then I may make false assumptions that something else is true when in fact that alternative is not true.


    While I agree that it is an extreme example, the example illustrates the concept that if you ignore significant warnings when you question whether you can trust the documentation, then you're an idiot. In a situation like that, independent research and review is mandatory prior to acting.

    Not oh-so-many years ago, I was babysitting some contractors while they audited and cleaned our installed fiber optic cabling. A telecom tech came through tearing down unused fiber circuits. We got to chatting and he made a comment that the documentation for one circuit didn't match what he was seeing on the fiber panels. Instead of getting independent confirmation, he made a guess and just took down a circuit anyway. Of course, it ended up being a live circuit, and a few minutes later when my pager went off, I helped guide him in rebuilding the circuit.

    Why didn't I stop him? I was watching contractors and working on a different project as well. So? Well, since management took building fiber circuits away from the network engineers, not my job. I don't like using that excuse, but this guy had other problems with detail. Sometimes the best way to learn is to get burned. Due to other circumstances and happenings, he is no longer with our organization.

    The amount of effort I will put in varies, but if the documentation is questionable to me I try to find an authoritative source. Then, if nothing else, when the fecal matter impacts the rotating blades, I can say and document the steps that I took to try to avoid having ended up where I did. But to completely ignore documentation with major warnings (even such things less life-threatening like "This package is incompatible with SuperSoft v3.41b and will cause the system to crash") without independent verification, well, you get what you deserve.
  • moz 2010-10-05 15:51
    Chris Cowdery:
    You will find me poring over my code, not pouring.....

    I hope I would seldom have the opportunity to find your boss pouring bile and vitriol over it.
    charles:
    UK says:
    1. Broiling means you're not from around here.
    2. Grilling means cooking in the oven under the flame/heating element.
    3. Barbecuing means cooking (usu. outdoors) over a fire, sometimes with hickory or other wood chips for flavor.

    Pretty much, although it's pretty common to have a grill as a distinct part of the cooker, either between the oven and the hob or somewhere near eye level. "In the oven" means in the part where you'd bake or roast things here.

    It was a pretty poor choice of words even without the dialect term, though, as <English cookery term> being a foreign word would not prevent a cook from China or France from following a recipe.
  • Ross Patterson 2010-10-05 15:55
    The operation of all computer programs can be understood without any documentation.


    Ay, theres the rub. The operation of all computer programs can be understood, but the intent may not be. One key purpose of all program documentation is to record what that intent was. I can't count the number of times I've either had to read the external documentation or write it after a code archeology session, just to be able to say that a routine or program accomplished it's goal. What it did was usually never in question, but whether it did what it should do often was.
  • BOB 2010-10-05 16:10
    Tom7:
    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.


    The word underneath broiled is ὀπτοῦ (pronounced optos) and includes many means of applying heat to an object to cook it. It can mean roast , broil, or bake. The choice of "broiled" in the translation implies cooking by flame rather than glowing coals.
  • Peter - I'm here for the fish 2010-10-05 16:36
    BOB:
    Tom7:
    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.


    The word underneath broiled is ὀπτοῦ (pronounced optos) and includes many means of applying heat to an object to cook it. It can mean roast , broil, or bake. The choice of "broiled" in the translation implies cooking by flame rather than glowing coals.

    Actually, what you have written their would be pronounced "opt-ow", although I have no idea what the original word is.
  • nope 2010-10-05 16:43
    On one proejct I was on, we came up with the term vagocity granted we never came up with a spelling. When doing documentation, we would often respond to questions about levels of detail with "Turn up the vagocity".

    For the unknowning, this is a blend of the word vague and viscocity.
  • the old rang 2010-10-05 16:54
    I wrote 'documentation' for many years. I was damned good at it.

    You failed to note several things in the assessment in proper order.

    (and programming is not 'self documenting'... ESPECIALLY if it is done efficiently)

    The golden rule I lived by, to make sure what I wrote, could and would be understood, was simple.

    Write to the lowest common denominator of ignorance (stupidity can never be taken for granted, and never compensated for. The ignorant lack knowledge, but might be taught. To quote Ron White... You can't fix stupid)

    If you write instructions clear enough to be followed, no matter what the level of 'knowledge' the person may have, the instruction will be used as a guideline, to the point of need. With experience, they will be used when 'new' things occur, or, when old things blow up.

    I wrote instructions to be followed sequentially, in best case scenario, and, constantly allowing for all the other cases to be covered... period... including... stop and call for help!!! (and check to see if power is on at main circuits)

    One set of instructions I wrote, lasted through 3 system changes...

    (even though most 'things' changed... the instructions were still the bible that shop followed almost 20 years after I left. Then things changed too much)

    Last two steps I always did, I had someone follow the instructions, that never done the task before. I watched, silently, spoke to them to learn where and why they got stuck.

    After fixing what I learned...

    The same steps were followed, with another 'newbie'...

    Then fixed what seemed to need it.

    The other rule I learned, early in the game (programming, not procedures, was, comments were what you thought the computer was going to do... Reality of what the computer did would slap you in the face, every time.
  • The Compiler 2010-10-05 17:07
    the old rang:

    The other rule I learned, early in the game (programming, not procedures, was, comments were what you thought the computer was going to do... Reality of what the computer did would slap you in the face, every time.

    Syntax error, insert ")" to complete Expression
  • My Two Cents 2010-10-05 17:23
    Jay:
    Something you perhaps imply but that is often ignored is that documentation can serve three very different purposes:

    1. Communicate information between members of the project team during the course of the project.

    2. Record information about the project for future reference. This could mean to people who were not involved in the project when it was developed, or to people who were involved who are coming back at a later time and may not remember.

    3. Help someone to formulate his thoughts.

    For example, probably the most important purpose of a requirements paper is #1: To communicate the requirements for this project from the users to the developers.

    A users manual is primarily for #2. It should describe how to use the system for people who come along in the future.

    A class diagram or entity-relationship diagram's main purpose might be to help the person writing it get his thought in order. I often draw ERDs, for example, that I know no one else will ever look at, just to help myself get it all together.

    Of course documents can serve more than one of the above purposes.

    Once stated that way, it's obvious that type 2 documents must be carefully preserved and kept current, while type 1 and 3 need not be. Indeed on type 3 documents, I often scribble ERDs or data flow diagrams on a piece of paper just to work out what I need, and then promptly throw them away once I've created the database or whatever.

    One of the biggest time-wasters in many organizations I've worked in is the requirement that documents be kept updated after their useful life has ended. I've had many times when I was required to update a systems design document after programming was complete to reflect any changes made in the course of development, when I knew full well that now that development was complete, no one was ever going to look at these documents again. It reminds me of the joke of the aspring writer who is told by a publisher, "Your submissions are so bad, we have to rewrite them before we throw them away." Why update something just before filing it in the Black Hole Archive?


    Further to that, the 3rd type of document is often most useful the less complete it is - it needs to give enough information for a developer to know where things happen so that they can go in and have a look at how they do. In support roles, most of the time can be spent looking for problems. Documentation should provide sufficient information for a developer to get a high-level view, but not so much that they would think they know HOW simply by reading it. The best way to develop an understanding of the HOWs is to step through them in your head. This might mean reading and rereading code (all the time thinking WTF is going on here) until you get your 'AHA' moment. The biggest thing with the 3rd type of documenation (and I suspect this was largely Alex's point) is that it shouldn't lull readers into a false sense of security. Nor should it leave them scratching their heads. It should provide enough detail for a techo to start getting their hands dirty (which is, after all, what they're paid to do) but not so much detail that they have already made assumptions about implementations.

    As Jay points out, some of this documentation might have limited life - as I investigate an issue, I might scribble notes of ideas that I want to come back to (sometimes even related to other issues), and moments where I realise how unrelated functionality works. Documentation for the sake of documentation is rarely a good thing. Documentation should have a purpose (or else it can be avoided), and if the purpose is to stimulate the developer, then it is more of a directive on what tasks are done where, rather than specifics about how they work. It's like working with interfaces - we don't care about the implementation detail - someone hired for support can work through code chunks to work out the specifics (even if the code is badly written, has meaningless variable names and is badly commented - it just takes longer), they might just need a gentle shove to work out where to look.

    It seems increasingly, the world is catering for stupid people - and in doing so, is just encouraging further generations of stupid people. To get the best out of people (especially highly technical people), you need to offer them a challenge. Give them enough to go smell out the exact problem themselves. This not only helps them develop their own skill sets, but tends to encourage a sense of ownership and pride over fixes. People will be proud of their achievements - especially if they feel they've worked hard toward them, and (perhaps more importantly) have had a license to fiddle as they see fit (which is more likely with less documentation).

    Catering for idiots only breeds idiots. Catering for geniuses will drop off relatively few idiots, and force others to stand up and show their smarts. If people feel they are trusted by management to investigate, design, fix etc then the results all round can only be beneficial!

    erat: Caeser had erat for tea
  • boog 2010-10-05 17:33
    Moshe:
    The operation of all computer programs can be understood without any documentation.


    This statement is incomplete. What a computer program does can be understood without any documentation. But that is not necessarily true about the Why.

    To add to this, it can also be particularly difficult to fully understand the what if your code is interacting with third-party libraries or services. In such cases, documentation can be very handy for supporting developers who need to understand what's happening external to the software they support.
  • Coyne 2010-10-05 18:00
    It's great to see someone thinking along the same lines I've been thinking for a while. I've been trying to get my organization to do better documentation for about 3 years now...with only moderate results.

    My thinking has revolved around the idea of "knowledge-versus-data". To understand, I really need knowledge (not data, which has to be condensed and interpreted to become knowledge). The problem is that expressing knowledge comes hard for most people because it means that you must think before answering questions like: Why did the system get built this way? How does this program work with that program? What was the purpose of this feature?

    What we need is the picture on the front of the puzzle box, which can only be communicated mind-to-mind and requires one to actually write down what one knows. What programmers and managers (in my experience) normally want to produce is precise-to-the-micron detailed measurements of the pieces in the box, because that can be done assembly line by rote, without all that hard thought (even if it takes 90% of the development schedule).

    It can even be done by filling in the blanks of a template! (Shudder of horror.)

    Knowledge is the why, how, where and when of the system that no computer will ever be able to distill. I have spent months trying to hammer this into heads: A top-level system overview is much more useful than a detailed program-level analysis, requirements, or even design document. With that top level overview, the programmer can get a quick and priceless start into understanding a system; then the programmer can read the source for data-details. (And if that is too hard then let's build another program to grovel through the source and distill the details.)

    That might be the only area where you need to give more consideration: Automation. In your document, you listed "Database Documentation" and "Component/Dependency Diagrams". These collections are mostly data, and data is the domain of the computer. We sell automation: "Let's eat our own dog food" by having the computer maintain these data-oriented documents, which it can do cheaply, accurately, and often (if that is necessary). It is a nearly complete waste of time to maintain any such object by hand if the computer can do it.

    The bottom line is, it isn't the quantity of documentation, it's the effectiveness: And knowledge is always more effective than data, when produced by humans. Let computers produce data.
  • mph 2010-10-05 18:02
    What's wrong with a recipe for salted water?
  • Herby 2010-10-05 18:08
    What to document and how much to do, and what it should look like. Yes, I follow a VERY simple rule.

    Document for yourself, for in 6 months you will have forgotten why you did what you did, and need to understand your old thought processes.

    One can easily verify that this is needed by looking back on some code (take your pick, all code qualifies) that you haven't looked at for 6 months (possibly shorter). Can you understand it. Do you remember why you did the "+1" somewhere? If you don't have the answer, then you didn't document what you did, and it is close to being useless.

    Repeat after me: "Document for yourself!". YOU WILL need it!
  • Sutherlands 2010-10-05 18:16
    Anonymous Coward:
    Tom7:
    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.

    Instead of fairy tales, you'd be better off checking a dictionary:

    http://www.merriam-webster.com/dictionary/broil

    Wow, someone's insecure.
  • Simon 2010-10-05 18:26
    Jay:
    Once stated that way, it's obvious that type 2 documents must be carefully preserved and kept current, while type 1 and 3 need not be. Indeed on type 3 documents, I often scribble ERDs or data flow diagrams on a piece of paper just to work out what I need, and then promptly throw them away once I've created the database or whatever.


    On the other hand, type 1 and 3 documents are often the most useful when coming back to something a few years later - they don't just cover what someone thought was important, but what they were thinking when decisions were being made. That can be critical in understanding why something was done in a particular way, and whether the people who made those decisions understood the problem correctly.
  • boog 2010-10-05 18:28
    I agree with the overall spirit of this article, that documentation should be written with the sole purpose of documentation in mind: communication. But I'm not so sure that the advice here is all that... appropriate.

    I'd love to have seen some suggestions on how to write robust and effective documentation that is useful, rather than just "embrace incompleteness" or when to archive. How about advice on writing documentation so that it is easy to keep it up to date (yes, it's possible)? How about advice on how to tell which details will be useful in a document and which won't, such as program behavior, interaction, and other public functionality (very useful) vs. static structure and low-level attributes (not so much)?

    I normally enjoy the soapbox articles (so please don't just delete my non-supportive comment, Alex), but I'm honestly a little disappointed with this one.
  • catgull 2010-10-05 21:42
    Don't you mean do***entation?
  • BA 2010-10-05 21:56
    As a Business Analyst I agree with most of what was written, with a couple of notes:

    1) The volume of documentation should be function of the complexity, not the size of what is being developed.

    2) ALL documents should be tied to a specific version/release of the software. Each successive version then gets a new version of the document, with the ability to track all the changes that came through.

    3) You need to include WHAT (the design of what you intend to build), WHY (decisions you made about the design, including reasons for it differing to user requests) and HOW (implementation details).

    4) Not doing any documentation implies that you thing you will have a clue how your software is supposed to behave in 6 months, let alone being the one responsible for maintaining it in 5 years.

    Obviously YMMV depending on what you're working on.
  • Peter S. Conrad 2010-10-06 00:12
    Conciseness is crucial.
  • fermion 2010-10-06 00:31
    In Australia we grill...

    Grill

    Cooking meat (or other food) directly under (as in a gas or electric oven) or over the heat source (as on a grill). Moisture is held in the food by the high cooking temperatures which quickly "seal in" flavour. This cooking method is ideal for tender cuts of meat.

    Barbecue

    Cooking food on a rack or plate over direct heat in a charcoal or gas barbecue or over hot coals.
  • da Doctah 2010-10-06 03:17
    Gator BBQ:
    I've always felt the code was the documentation, so I keep the variables short to make it more readable (just start with 'a' and work your way down the alphabet). I also keep the method names short and consistent to help with comprehension, 'm1', 'm2' etc.


    If I thought you were serious, I'd be compelled to recommend that you be taken out and slapped.

    On second thought, I recommend that anyway on the grounds that someone might believe you were serious.
  • madjo 2010-10-06 03:45
    Nice developer-sided view of documentation. Here is my take:

    Documentation is supposed to describe how a system is supposed to work. And with that I do mean as complete as possible.

    I am a tester, and my job is to test the software BASED on the documentation at hand. If something isn't documented, I can't possibly test it, because I can't predict how something will work.

    I read the docs, and based on that and following various techniques (and which one depends on the type of program and the severity of its effect on the business processes it will have), I write my testcases. That could be a financial test (in case it has severe implications for the financials of the company), a semantic/syntactic test (if it's just a change in a screen), or a white box test, or one of the many other different tests.

    But all of those a dependent on the availability of documentation and the quality thereof. If it's a shoddy document, I will say so, and I will send the designer back to the drawing board.
    Ideally (and in most assignments I've been in this has been the case), you have teams made up of one or more designers, one or more developers and one or more testers.
    That's the best way to ensure the best quality of your project, and the best way of it succeeding too.
  • Mick T 2010-10-06 04:32
    BA:
    As a Business Analyst...


    Uh oh...

    BA:

    1) The volume of documentation should be function of the complexity, not the size of what is being developed.


    I think this completely misses the point. Say you have an extremely complicated piece of calculation logic. Why should documentation for it be more volumous than usual? Why would you want pages and pages to describe it? It would be much better to provide a high level description of the algorithm, with a few formulas, references to relevant theory, or even a flowchart, and leave the complexity in the code.

    Complexity = volume of documentation is non-sensical, except in so far as trivial things need not be documented.

    BA:

    2) ALL documents should be tied to a specific version/release of the software. Each successive version then gets a new version of the document, with the ability to track all the changes that came through.


    You have to be kidding. So your solution to document complexity is to raise to the power the number of documents in existence?

    Who is going to do this and where are they going to get the time? Who is going to manage this process to make sure it happens? Who is going to allocate their budget for all of this to happen? And most importantly, how many different documents are people expected to wade through in order to gain even a partial understanding of your system?

    Hey, I'm on a deadline. If I'm confronted with a 150 page behemoth I'm already annoyed that the person who created it didn't care about the reader and didn't do a better job of trimming the fat*. There's no way on earth I'm going to read 20 of those, nor am I going to "track changes".

    Just give me an overview of the current state of the system and what you want done. Is that so hard?

    *For highly-regulated industries such as healthcare and defense, large documents would be fine, but for your average corporate app it's just unnecessary.

    BA:

    3) You need to include WHAT (the design of what you intend to build), WHY (decisions you made about the design, including reasons for it differing to user requests) and HOW (implementation details).


    How does this increase the usefulness of documents? The entire point of Alex's post is that we, most of us, already take these things you've mentioned for granted and do them because that's what we've learned Is Good, yet these approaches often do not produce effective or useful documentation at all.

    So when you said you mostly agree with Alex, what you meant is that you didn't understand and barely read the post, but wanted to offer your contrary opinions anyway without offering any sort of supporting argument that would negate the considerable evidence that Alex presented in his post because you think you're right anyway.

    BA:

    4) Not doing any documentation implies that you thing you will have a clue how your software is supposed to behave in 6 months, let alone being the one responsible for maintaining it in 5 years.


    A high level description of the system should be all that's necessary to jog your memory. If that doesn't work, there's nothing wrong with diving into the code and finding out for yourself. I mean, if you were brought onto a project you had nothing to do with, you'd have to do that anyway to work it out. What's the problem?

    I don't get the "you won't understand what you did 6 months ago so you absolutely must document everything!" argument. Who cares? Firstly, it will come back to you as you work with it. Secondly, you might be put onto a project with no documentation at all, and it'll be your job to figure it out. If you can't handle that, maybe this isn't the profession for you.

    It looks like I'll still be happier when BA's are restrained from interfering in the technical process. :)
  • madjo 2010-10-06 05:29
    Mick T:
    BA:
    As a Business Analyst...


    Uh oh...

    BA:

    1) The volume of documentation should be function of the complexity, not the size of what is being developed.


    I think this completely misses the point. Say you have an extremely complicated piece of calculation logic. Why should documentation for it be more volumous than usual? Why would you want pages and pages to describe it? It would be much better to provide a high level description of the algorithm, with a few formulas, references to relevant theory, or even a flowchart, and leave the complexity in the code.

    Complexity = volume of documentation is non-sensical, except in so far as trivial things need not be documented.

    As a testengineer, I'd actually prefer to have it this way. I'd rather have the full formula, and then a description of what it does, so that future developers/designers/testers know what the formula entails. You're not just documenting for right now, but also for tomorrow.


    BA:

    2) ALL documents should be tied to a specific version/release of the software. Each successive version then gets a new version of the document, with the ability to track all the changes that came through.


    You have to be kidding. So your solution to document complexity is to raise to the power the number of documents in existence?

    Do you offer all packages for a new version of a changed system, or just the changed source files?

    Who is going to do this and where are they going to get the time? Who is going to manage this process to make sure it happens? Who is going to allocate their budget for all of this to happen? And most importantly, how many different documents are people expected to wade through in order to gain even a partial understanding of your system?

    Even documentation can be handled using a version control system. Just branch off.
    And it's usually a BA who maintains that.

    But it is indeed very important that they communicate which files are changed, and that there is time for review sessions. So that you can say "this set of documentation is approved and are now final, and won't be changed until the next version of the application."

    Hey, I'm on a deadline. If I'm confronted with a 150 page behemoth I'm already annoyed that the person who created it didn't care about the reader and didn't do a better job of trimming the fat*. There's no way on earth I'm going to read 20 of those, nor am I going to "track changes".

    Wow, a lot of assumptions, I hope you don't develop in the same way.

    Just give me an overview of the current state of the system and what you want done. Is that so hard?

    Could it be possible to have both?

    *For highly-regulated industries such as healthcare and defense, large documents would be fine, but for your average corporate app it's just unnecessary.

    Respectfully, I disagree. Even in the case of corporate applications it's important to have good documentation.

    BA:

    3) You need to include WHAT (the design of what you intend to build), WHY (decisions you made about the design, including reasons for it differing to user requests) and HOW (implementation details).


    How does this increase the usefulness of documents? The entire point of Alex's post is that we, most of us, already take these things you've mentioned for granted and do them because that's what we've learned Is Good, yet these approaches often do not produce effective or useful documentation at all.

    And yet, I encounter many instances where what the designers designed, the developers didn't build, and what the developers built, the designers didn't design. And then it's up to me the clear the mess.

    So when you said you mostly agree with Alex, what you meant is that you didn't understand and barely read the post, but wanted to offer your contrary opinions anyway without offering any sort of supporting argument that would negate the considerable evidence that Alex presented in his post because you think you're right anyway.

    BA:

    4) Not doing any documentation implies that you thing you will have a clue how your software is supposed to behave in 6 months, let alone being the one responsible for maintaining it in 5 years.


    A high level description of the system should be all that's necessary to jog your memory. If that doesn't work, there's nothing wrong with diving into the code and finding out for yourself. I mean, if you were brought onto a project you had nothing to do with, you'd have to do that anyway to work it out. What's the problem?


    How about if you are replaced by Developer Junior, because you have been assigned to another project? Oops, documentation to jog YOUR memory isn't enough to help junior.
    And me, as a tester, I don't dive into code, unless the task asks for a white box test, which is quite rare.
    Without proper documentation how do you know what the business wants the application to do?

    I don't get the "you won't understand what you did 6 months ago so you absolutely must document everything!" argument. Who cares? Firstly, it will come back to you as you work with it. Secondly, you might be put onto a project with no documentation at all, and it'll be your job to figure it out. If you can't handle that, maybe this isn't the profession for you.

    And maybe the documentation could speed up your work greatly. Instead of second guessing what they might have meant with function_x, you'd know, and don't have to read through thousands of lines of code.

    It looks like I'll still be happier when BA's are restrained from interfering in the technical process. :)

    And I'll be happy when developers actually build what was designed.
  • TheJasper 2010-10-06 05:34
    Mick T:
    BA:
    As a Business Analyst...


    Uh oh...


    Lets set the mood early by revealing our prejudices.

    Mick T:

    BA:

    1) The volume of documentation should be function of the complexity, not the size of what is being developed.


    I think this completely misses the point...


    I think you need to look up what complexity is. If you are going to bash someone about is use of complexity you should be exact. There are many different types of complexity and for most people its about how many parts is has.

    Mick T:

    BA:

    2) ALL documents should be tied to a specific version/release of the software. Each successive version then gets a new version of the document, with the ability to track all the changes that came through.


    You have to be kidding. So your solution to document complexity is to raise to the power the number of documents in existence?

    Who is going to do this and where are they going to get the time? Who is going to manage this process to make sure it happens? Who is going to allocate their budget for all of this to happen? And most importantly, how many different documents are people expected to wade through in order to gain even a partial understanding of your system?


    Actually this is a good idea. If you are going to document then tie it to the version. Otherwise don't document. This has nothing to do with the amount of documentation. As to who is supposed to do it? Depends on the doc but I don't accept lazy programmers who think documentation is beneath them.


    Mick T:

    Just give me an overview of the current state of the system and what you want done. Is that so hard?


    yes.

    Mick T:

    So when you said you mostly agree with Alex, what you meant is that you didn't understand and barely read the post, but wanted to offer your contrary opinions anyway without offering any sort of supporting argument that would negate the considerable evidence that Alex presented in his post because you think you're right anyway.


    You just want to bash someone because he's a BA and because you hate documentation.

    Mick T:

    I don't get the "you won't understand what you did 6 months ago so you absolutely must document everything!" argument. Who cares? Firstly, it will come back to you as you work with it. Secondly, you might be put onto a project with no documentation at all, and it'll be your job to figure it out. If you can't handle that, maybe this isn't the profession for you.


    No one said document everything.

    A high level description is not a basis for anything but a begin, it won't help me solve a specific bug.

    It looks like I'll be happier not to ever have to work on anything you've worked on.
  • renewest 2010-10-06 06:33
    Given infinity time and resources, who needs good documentation? Just study the code.
  • OldCoder 2010-10-06 06:48
    The Compiler:
    the old rang:

    The other rule I learned, early in the game (programming, not procedures, was, comments were what you thought the computer was going to do... Reality of what the computer did would slap you in the face, every time.

    Syntax error, insert ")" to complete Expression

    Stupid poxy compiler! If you knew that a ")" was needed to complete the expression, why didn't you fucking well put one in?

    Captcha: abbas. Something to do with Sweden?
  • Programmer (the same one) 2010-10-06 07:44
    Just wanted to say... great post!
    Guess I'll keep it at arm's reach, and hand it over when appropriate.

    Getting to a new job usually includes someone sitting you on your desk, handing you a 200 page sort of user guide and system design - whose are at least five years old - and being told "read this... it's a bit outdated, but it may help you get started". It rarely does... just makes you sleepy and bored even before cracking some code and finding out that - guess what - you'll be maintaining Frankenstein-style code.

    I'm sick of dusty docs.

    Captcha: odio, hate in Spanish... just perfect
  • Captain Obvious 2010-10-06 08:12
    As a technical writer who has previously done UML, flow charts, and various other design and project documentation, I'll take user manuals over that any day!
  • ASDF 2010-10-06 08:50
    I was looking for a WTFstory, instead I find a small essay paper on writing documentation.
  • frits 2010-10-06 08:51
    madjo:
    Nice developer-sided view of documentation. Here is my take:

    Documentation is supposed to describe how a system is supposed to work. And with that I do mean as complete as possible.

    I am a tester, and my job is to test the software BASED on the documentation at hand. If something isn't documented, I can't possibly test it, because I can't predict how something will work.

    I read the docs, and based on that and following various techniques (and which one depends on the type of program and the severity of its effect on the business processes it will have), I write my testcases. That could be a financial test (in case it has severe implications for the financials of the company), a semantic/syntactic test (if it's just a change in a screen), or a white box test, or one of the many other different tests.

    But all of those a dependent on the availability of documentation and the quality thereof. If it's a shoddy document, I will say so, and I will send the designer back to the drawing board.
    Ideally (and in most assignments I've been in this has been the case), you have teams made up of one or more designers, one or more developers and one or more testers.
    That's the best way to ensure the best quality of your project, and the best way of it succeeding too.


    Is it too much to ask the developer for clarification? Does your company's management allow the testers to direct developer effort? There is not always going to be enough time to get both the code and the docuemntation correct. I'll take correct code over documentation any day.
  • Bert Glanstron 2010-10-06 09:12
    Dear Remy Martin,

    In case you can’t tell, this is a grown-up place. The
    fact that you insist on not posting an article on time
    clearly shows that you’re too drunk and too irresponsible
    to be using recreational drugs.

    Go away and grow up.

    Sincerely,
    Bert Glanstron
  • Slicerwizard 2010-10-06 09:26
    "Of all people, I have a pretty high standard for doing things right."

    He's joking, right?
  • TheJasper 2010-10-06 09:27
    frits:

    Is it too much to ask the developer for clarification? Does your company's management allow the testers to direct developer effort? There is not always going to be enough time to get both the code and the docuemntation correct. I'll take correct code over documentation any day.


    How do you know what is correct code? How do you ask a developer for clarification if he just got hit by a bus?
  • Slicerwizard 2010-10-06 09:29
    "As I spent the next week pouring over the documentation templates"

    Like I was saying...

    I'm sure there are more eggcorns in this masterpiece.
  • TheJasper 2010-10-06 09:31
    OldCoder:

    Captcha: abbas. Something to do with Sweden?


    Try chairman of the PLO and former PM of the PA. Either this forum is run by terrorists, you are a terrorist or all those people telling us to be scared of terrorists are terrorists. Either way I'm frightened.
  • frits 2010-10-06 09:39
    TheJasper:

    How do you know what is correct code?

    Correct code is code that works as intended and agreed to by the customer.
    TheJasper:

    How do you ask a developer for clarification if he just got hit by a bus?

    The old hit-by-a-bus analogy rears its head. Why can't it be "What if the developer quits suddenly and moves to Katmandu?"? What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?
  • itsmo 2010-10-06 09:40
    Mike:
    MLD:
    Hmmm. Your description of "broiling" in the US sounds exactly like "grilling" in the UK.

    So what is "grilling" in the US? Something you only do outside, like "barbecuing" in the UK...?


    I'm a bit of a barbecue snob, and grilling is not the same as barbecue.

    Broiling is cooking, usually indoors in an oven, at high radiant heat with the food placed close to the heating element.

    Grilling is cooking, usually outdoors, over direct heat, usually provided by gas burners or charcoal.

    Barbecue is cooking meat over a long period of time at relatively low heat. Pit barbecues can hold hundreds of pounds of meat and can take up to 8 hours to cook. Low and slow.


    or this
    http://en.wikipedia.org/wiki/Grilling
  • itsmo 2010-10-06 09:43
    mainframe_guy:

    Best part of the article:

    The ease of extracting and understanding these specifications varies on the complexity of the subject at hand.

    * A 8’ length of 2” x 4” is just that, less planing

    And this sums up the end problem. A two-by-four isn't actually 2" by 4". Hence, there is still ambiguity in the sentence above. This is the proof that documentation (less is more) is hard to write.

    For the record, I work in a gigantic company. We have almost zero documentation due to Agile PMO with a horde of professional coders imported by tier one outsourcing firm. These guys work HARD to make their sprint dates. They have troubling reading the existing code, have little UML literacy skill and sometimes don't understand the problem (eg a stopped check can only be stopped once)... and none of that matters because documentation is the first item cut when faced with the sprint deadline.

    The best solution we have right now, create very coloful and fancy looking powerpoints to describe architecture and implementation detail. Those work great in the 20+ person daily meetings.

    As for the comment about old documentation perceived as inaccurate. I agree with that. However some of the best documentents I have seen are from the 1970-80s regarding how the ACP Airline Control System assembler systems run today's ATM network.

    FTFY
  • Ben 2010-10-06 10:01
    TRWTF is that your company's website has contact details in a background image, including "www.inedo.com". O RLY IS DAT TEH WEB ADDRESS I'M ON??
  • TheJasper 2010-10-06 10:07
    frits:
    TheJasper:

    How do you know what is correct code?

    Correct code is code that works as intended and agreed to by the customer.


    How do you know what was intended and agreed to?

    frits:

    TheJasper:

    How do you ask a developer for clarification if he just got hit by a bus?

    The old hit-by-a-bus analogy rears its head. Why can't it be "What if the developer quits suddenly and moves to Katmandu?"? What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?


    hit by a bus == hit by a meteor == had a heart a attack == became the unabomber 2.0 == quite and moved to katmandu

    You don't actually have to handle each case where a developer suddenly becomes unavailable as a separate case.
  • John Rasch 2010-10-06 10:10
    Ben:
    TRWTF is that your company's website has contact details in a background image, including "www.inedo.com". O RLY IS DAT TEH WEB ADDRESS I'M ON??


    Clearly you are not visiting the correct website if you believe the contact details are stored in a background image.
  • frits 2010-10-06 10:12
    TheJasper:
    frits:
    TheJasper:

    How do you know what is correct code?

    Correct code is code that works as intended and agreed to by the customer.


    How do you know what was intended and agreed to?

    frits:

    TheJasper:

    How do you ask a developer for clarification if he just got hit by a bus?

    The old hit-by-a-bus analogy rears its head. Why can't it be "What if the developer quits suddenly and moves to Katmandu?"? What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?


    hit by a bus == hit by a meteor == had a heart a attack == became the unabomber 2.0 == quite and moved to katmandu

    You don't actually have to handle each case where a developer suddenly becomes unavailable as a separate case.


    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

    "What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?"


  • History Lesson 2010-10-06 10:30
    3 Weeks Ago on Thursday: No TDWTF
    2 Weeks Ago on Monday: No TDWTF
    1 Week Ago on Tuesday: No TDWTF
    This Week on Wednesday: No TDWTF
  • TheJasper 2010-10-06 10:34
    frits:

    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

    "What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?"


    You didn't address my question either, you avoided it. Your 'comment' about why can't it be 'moved to katmandu' implied you saw those as separate cases which needed to be addressed first.

    However, it isn't very likely that everyone on a given project shares all knowledge with everyone else.

    Generally speaking you want to avoid having a person who is the only source for some information. This will happen anyway but you want to avoid it. One way of doing that is documentation.

    If it is worth managing the cost of that risk depends. Thats what risk assessment is about. For a website that 2 people read, probably no. For an application which is used by 50000 users then most likely yes. How you actually come to the conclusion of what constitutes enough risk is not an exact process.
  • Bert Glanstron 2010-10-06 10:41
    frits:
    TheJasper:
    frits:
    TheJasper:

    How do you know what is correct code?

    Correct code is code that works as intended and agreed to by the customer.


    How do you know what was intended and agreed to?

    frits:

    TheJasper:

    How do you ask a developer for clarification if he just got hit by a bus?

    The old hit-by-a-bus analogy rears its head. Why can't it be "What if the developer quits suddenly and moves to Katmandu?"? What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?


    hit by a bus == hit by a meteor == had a heart a attack == became the unabomber 2.0 == quite and moved to katmandu

    You don't actually have to handle each case where a developer suddenly becomes unavailable as a separate case.


    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

    "What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?"



    You are an idiot and should be banned from your mommy and daddy's modem.
  • TheJasper 2010-10-06 10:44
    TheJasper:
    frits:

    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

    "What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?"


    You didn't address my question either, you avoided it. Your 'comment' about why can't it be 'moved to katmandu' implied you saw those as separate cases which needed to be addressed first.

    However, it isn't very likely that everyone on a given project shares all knowledge with everyone else.

    Generally speaking you want to avoid having a person who is the only source for some information. This will happen anyway but you want to avoid it. One way of doing that is documentation.

    If it is worth managing the cost of that risk depends. Thats what risk assessment is about. For a website that 2 people read, probably no. For an application which is used by 50000 users then most likely yes. How you actually come to the conclusion of what constitutes enough risk is not an exact process.


    Not to mention people you need may not be around for other reasons. They could be on location, work different hours, be on vacation... If I lose a day because I can't ask a Fred an important question until tomorrow then that is an expensive question.
  • JJ 2010-10-06 10:51
    The Article:
    No amount of documentation will help the average developer understand brilliant systems like The Policy Entry System and The Customer-Friendly System.

    Am I really the first to point out that Alex misspelled "brillant"?
  • TheJasper 2010-10-06 10:55
    JJ:
    The Article:
    No amount of documentation will help the average developer understand brilliant systems like The Policy Entry System and The Customer-Friendly System.

    Am I really the first to point out that Alex misspelled "brillant"?

    no
  • Jim 2010-10-06 10:55
    I wonder if the reason the project management team asked for the database table design was because programmers would just start coding without thinking things through first. At least this way they would be forced to stop and write something
  • Anonymous 2010-10-06 11:10
    Jim:
    I wonder if the reason the project management team asked for the database table design was because programmers would just start coding without thinking things through first. At least this way they would be forced to stop and write something

    This isn't a problem that's solved by documentation - this is a problem that's solved by hiring good programmers. If you don't trust your own staff enough to let them get on with the job then you need to improve your hiring practices. Better to hire good staff than to force pointless write-only documentation onto the team.
  • Max 2010-10-06 11:12
    TheJasper:
    frits:
    TheJasper:

    How do you know what is correct code?

    Correct code is code that works as intended and agreed to by the customer.


    How do you know what was intended and agreed to?


    If you get paid
  • TheJasper 2010-10-06 11:17
    Anonymous:
    Jim:
    I wonder if the reason the project management team asked for the database table design was because programmers would just start coding without thinking things through first. At least this way they would be forced to stop and write something

    This isn't a problem that's solved by documentation - this is a problem that's solved by hiring good programmers. If you don't trust your own staff enough to let them get on with the job then you need to improve your hiring practices. Better to hire good staff than to force pointless write-only documentation onto the team.


    You don't always have access to "good programmers". Good programmers tend to be in the minority. However it still holds for good programmers. In fact good programmers start by making a design even if the throw it away. Actually that could well be the difference between a programmer and an "engineer" (developer or whatever). A programmer just goes in and does stuff.

    Forcing pointless documentation will still be pointless in any situation. The point is documentation isn't always pointless. Forcing a particular form of documentation is also a way of making room in the process. If you don't ask for it you may also be cutting into valuable design time. Let's not forget that a bug in production is massively more expensive than one in development.
  • Anonymous Nitpicker 2010-10-06 11:20
    which documentation is to be maintained and which is to be archived (i.e., read-only and left to rot).

    itym "write-only"
  • frits 2010-10-06 11:27
    TheJasper:

    You didn't address my question either, you avoided it. Your 'comment' about why can't it be 'moved to katmandu' implied you saw those as separate cases which needed to be addressed first.

    If you say so. My comment was a humorous observation about the "hit-by-a-bus" cliche. It's morbid. Why can't we use a different one?
    TheJasper:

    Generally speaking you want to avoid having a person who is the only source for some information.

    I never said or implied this. Of course nobody wants this situation. See Strawman.
  • TheJasper 2010-10-06 11:28
    Max:
    TheJasper:

    How do you know what was intended and agreed to?

    If you get paid


    Good luck with that strategy. Repeat customers tell you are doing something right. Getting paid means they either can't or don't want to make an issue out of something. Not to mention the amount of poorly written contracts where regardless of what is or isn't delivered payment will have to be made.
  • boog 2010-10-06 11:29
    TheJasper:
    How do you know what was intended and agreed to?

    Requirements analysis, acceptance testing, customer-signoff, etc. There are ways.

    Maybe you meant "How do you know what was intended and agreed to without documentation?"

    TheJasper:
    hit by a bus == hit by a meteor == had a heart a attack == became the unabomber 2.0 == quite and moved to katmandu

    You don't actually have to handle each case where a developer suddenly becomes unavailable as a separate case.

    I don't think he was implying that each case should be handled separately; I think he was simply seizing the opportunity to ridicule the old "hit by a bus" justification (which you have to admit is pretty unlikely to ever happen).

    Rather than argue about it, why not seize the opportunity yourself? People almost never get hit by buses, but developers leave companies all the time. So if you really want to defend your apparent position on documentation, abandon your hypothetical "hit-by-a-bus," and embrace frits' practically-guaranteed "left-the-company."
  • TheJasper 2010-10-06 11:35
    frits:

    If you say so. My comment was a humorous observation about the "hit-by-a-bus" cliche. It's morbid. Why can't we use a different one?


    I don't mind, but that is not how I read your comment. From now on I will speak about developers falling in love and moving to Tahiti.
    TheJasper:

    Generally speaking you want to avoid having a person who is the only source for some information

    frits:

    I never said or implied this. Of course nobody wants this situation. See Strawman.


    Not a strawman. It's part of the whole point of documentation. Also, you did imply this by saying you could just ask the developer for clarification. Either way it's a situation which happens all too often and can be alleviated by documentation. Not by useless documentation, but by relevant documentation.
  • Whatever 2010-10-06 12:07
    History Lesson:
    3 Weeks Ago on Thursday: No TDWTF
    2 Weeks Ago on Monday: No TDWTF
    1 Week Ago on Tuesday: No TDWTF
    This Week on Wednesday: No TDWTF


    You forgot: This Week on Tuesday: No TDWTF
  • x-sol 2010-10-06 12:12
    Having long ago worked in food services let me help out here.

    Grill - a device used for grilling
    Broiler - a device used to broil things and some times make toast
    Oven - used to more often than not bake or roast something
    Smoker - usually made out of an old refigerator and user to slow cook something and saturate it with the flavor if the wood used and it's own juices

    BBQ - more often than not means it has BBQ sauce on it and not how fast or slow it was cooked on the grill

    ---

    I only saw a couple of good comments, but it seems like the older I get and the longer I've worked somewhere the more I suck. Whereas a lot of people start out sucking, but I think maybe the ones that already suck don't burn out and suck more the stay at a steady level of sucky...

    ---

    but then I do work with Paulla the brillant
  • da Doctah 2010-10-06 12:22
    x-sol:
    Having long ago worked in food services let me help out here.

    Grill - a device used for grilling
    Broiler - a device used to broil things and some times make toast
    Oven - used to more often than not bake or roast something
    Smoker - usually made out of an old refigerator and user to slow cook something and saturate it with the flavor if the wood used and it's own juices

    BBQ - more often than not means it has BBQ sauce on it and not how fast or slow it was cooked on the grill


    I agree with your definition, but then nobody said anything about "BBQ". The reference was to "barbecue", which is unrelated.
  • boog 2010-10-06 12:42
    I think he meant just what he said, "read-only," as in once you archive it you never modify it again. "Write-only" implies that it won't be a useful reference later, which is not necessarily the case.
  • Jay 2010-10-06 12:49
    Anonymous Coward:
    Tom7:
    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.

    Instead of fairy tales, you'd be better off checking a dictionary:

    http://www.merriam-webster.com/dictionary/broil



    Umm, whether or not you believe that the Bible is historically accurate, you must surely concede that it is a widely-published and widely-read book. Therefore, if it includes a word, by definition that word is part of the language. (If you're talking about an old translation, we might say that the word is obsolete, but it was part of the language at one time.)

    If a widely-read fairy tale -- Grimm's Fairy Tales perhaps -- includes a word, I think we'd pretty much consider that by definition that makes that word part of the language.

    Dictionary writers do not invent words: they discover words. A word must be part of the language before it is included in the dictionary. It is not at all nonsensical to say, "The dictionary made a mistake by not including such-and-such a word: it is widely used in print and in speech." It would be totally nonsensical to say, "My dictionary does not include the word 'Internet', therefore there is no such word and anyone who uses it is ignorant."

    Just because you don't like the Bible is no reason to get irrational about it.
  • wtf 2010-10-06 13:03
    frits:
    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

    "What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?"


    Okay, here's one answer:
    On my current job, I am documenting systems and processes for a medium-sized financial services company that you've never heard of. I don't have anything to do with the company's products, I'm just dealing with internal stuff, including HR, the website, the phone system, the data warehouse, and so forth. A large part of the justification for my position is summed up as "continuity of business". Continuity of business is the "developer leaves with <= 2 weeks notice" scenario, whether you call it "hit by a bus" or "moved to Kathmandu" or "got another job that paid more".
    I started at this position in March of last year. By June, two of the three developers whose work I was documenting had taken job offers at other companies, and left.

    Yes, it's worth the cost of managing that risk, because it's not a risk. It's a certainty: everybody leaves an organization at some point, and that is almost always done with two weeks or less of warning. The only thing you don't know is when this will happen. When they go, they take all of that stuff in their head and they walk out the door with it.
  • wtf 2010-10-06 13:04
    JJ:
    The Article:
    No amount of documentation will help the average developer understand brilliant systems like The Policy Entry System and The Customer-Friendly System.

    Am I really the first to point out that Alex misspelled "brillant"?


    No.
  • Kuba 2010-10-06 13:10
    Cbuttius:
    Actually the C++ FAQ discusses in depth why a circle is not a type of ellipse in OO. Although actually a read-only circle is a type of read-only ellipse, it's just once you allow an interface to modify an ellipse, you can't always run it on circles.

    Most of the time you don't end up with the perfectly designed OO solution but a practical one that works, and sometimes is even easier to maintain than the perfect one.
    I don't know what you imply by "practical" vs. "perfect", but the C++ FAQ discusses simply one of a widely misunderstood issues in OO programming as implemented in C++.

    C++'s type system has been designed with inheritance<=>equivalence in mind. If you derive from a base class, the derived class better be a total, no holds barred replacement for the base class -- in the sense that everywhere a base class can be used, the derived class can be used, too.

    The circle-is-an-ellipse is basically a very poorly thought out OO example that some half-wit put in a textbook one time, and it ended up being perpetuated ad nauseam. It simply does not fit within the C++ type system.

    If you're doing a project in C++, then Circle and Ellipse can surely derive from some base "graphical object/shape" class, but they cannot derive from each other (a Circle IS NOT an Ellipse, nor vice versa). A Circle is an Ellipse only in mathematics, not in C++. You can, of course, have an explicit Ellipse constructor that takes a single radius and produces a circular ellipse -- this would, nominally, obviate the need for a Circle class in most cases.

    Suppose you're designing a 2D computational geometry system -- whatever you code for an Ellipse is just generalization of code that would deal with a Circle, so the Circle class becomes a premature optimization. If profiling shows that whatever code simplification is afforded by a circular Ellipse is worth it, then you can insert the requisite r1==r2 tests into the code that deals with Ellipses, as a profile-guided optimization.
  • fool 2010-10-06 13:11
    The purpose of software documentation is to be an encyclopedia to the world that is the program or system. It should be a reference work that is useful to (a) new people who need to get up to speed on the basic concepts, and be shown some places to get started using or maintaining it, and (b) people trying to troubleshoot a problem or find out how to do something that the software does or that they think that the software might do but aren't sure whether it does and if so what it's called and how to do it. It should't be written in terms of itself. That is, jargon and new concepts need to be explained, not just thrown around. It should be written with awareness that things will change over time. Don't just ignore how things used to work, assuming that everyone is doing the new thing now; don't write about option x1 as if it is the only option or way to do Function X, or the person trying to get x2 to work will be really confused. It should be terse, but not an incomplete thing that pretends to be complete. For gods sake, that last point, if nothing else.... if not, or if it's just not going to be accurate or maintained, just delete it and do everyone a favor!
  • Kuba 2010-10-06 13:16
    Jay:
    Anonymous Coward:
    Tom7:
    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.

    Instead of fairy tales, you'd be better off checking a dictionary:

    http://www.merriam-webster.com/dictionary/broil
    Umm, whether or not you believe that the Bible is historically accurate, you must surely concede that it is a widely-published and widely-read book. Therefore, if it includes a word, by definition that word is part of the language. (If you're talking about an old translation, we might say that the word is obsolete, but it was part of the language at one time.)

    If a widely-read fairy tale -- Grimm's Fairy Tales perhaps -- includes a word, I think we'd pretty much consider that by definition that makes that word part of the language.

    Dictionary writers do not invent words: they discover words. A word must be part of the language before it is included in the dictionary. It is not at all nonsensical to say, "The dictionary made a mistake by not including such-and-such a word: it is widely used in print and in speech." It would be totally nonsensical to say, "My dictionary does not include the word 'Internet', therefore there is no such word and anyone who uses it is ignorant."

    Just because you don't like the Bible is no reason to get irrational about it.
    You assume that Bible translators weren't mistaken in their understanding of biblical languages, nor of their contemporary ones! Besides, the GP said nothing about broil not being a word -- so I don't see the point of your rant. The GP said that a word's definition should be looked up in the dictionary, not inferred from a text whose meaning is often vague by itself and subject to preconditioned thinking. You can't depend on Bible for circular-reference-definition of language.
  • Kuba 2010-10-06 13:19
    TheJasper:
    OldCoder:

    Captcha: abbas. Something to do with Sweden?


    Try chairman of the PLO and former PM of the PA. Either this forum is run by terrorists, you are a terrorist or all those people telling us to be scared of terrorists are terrorists. Either way I'm frightened.
    Abbas is a seafood company in Sweden. I like their red smoked roe paste -- got a taste for it as a kid visiting Sweden, now I pay regular visits to Ikea to get my fix.
  • frits 2010-10-06 13:25
    wtf:
    frits:
    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

    "What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?"


    Okay, here's one answer:
    On my current job, I am documenting systems and processes for a medium-sized financial services company that you've never heard of. I don't have anything to do with the company's products, I'm just dealing with internal stuff, including HR, the website, the phone system, the data warehouse, and so forth. A large part of the justification for my position is summed up as "continuity of business". Continuity of business is the "developer leaves with <= 2 weeks notice" scenario, whether you call it "hit by a bus" or "moved to Kathmandu" or "got another job that paid more".
    I started at this position in March of last year. By June, two of the three developers whose work I was documenting had taken job offers at other companies, and left.

    Yes, it's worth the cost of managing that risk, because it's not a risk. It's a certainty: everybody leaves an organization at some point, and that is almost always done with two weeks or less of warning. The only thing you don't know is when this will happen. When they go, they take all of that stuff in their head and they walk out the door with it.


    If one person has all the knowledge, you're managing things wrong. Proper teaming and sharing of the work can mitigate this risk. If developers can do each other's jobs, then the risk is everyone leaving at once--like I said originally.

    BTW- I would like to have someone document my code for me. How can I convince my manager to provide this?
  • The Bytemaster 2010-10-06 13:27
    Jay:
    Anonymous Coward:
    Tom7:
    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.

    Instead of fairy tales, you'd be better off checking a dictionary:

    http://www.merriam-webster.com/dictionary/broil



    Umm, whether or not you believe that the Bible is historically accurate, you must surely concede that it is a widely-published and widely-read book. Therefore, if it includes a word, by definition that word is part of the language. (If you're talking about an old translation, we might say that the word is obsolete, but it was part of the language at one time.)

    If a widely-read fairy tale -- Grimm's Fairy Tales perhaps -- includes a word, I think we'd pretty much consider that by definition that makes that word part of the language.

    Dictionary writers do not invent words: they discover words. A word must be part of the language before it is included in the dictionary. It is not at all nonsensical to say, "The dictionary made a mistake by not including such-and-such a word: it is widely used in print and in speech." It would be totally nonsensical to say, "My dictionary does not include the word 'Internet', therefore there is no such word and anyone who uses it is ignorant."

    Just because you don't like the Bible is no reason to get irrational about it.

    You forgot to mention that it is also a translation to english making word usage very relevent - even more so considering how many copies are made, read, etc.
  • ∃ Style. 2010-10-06 13:38
  • wtf 2010-10-06 13:43
    frits:

    BTW- I would like to have someone document my code for me. How can I convince my manager to provide this?


    I'd be happy to come and give your manager a presentation on the matter. On his dime, natch.

    Oddly enough, it seems this is more common in companies which don't develop software to sell, but are big enough to have developers making internal systems. I supppose this is because the company is not just the developer, but is also the consumer. If someone else is losing time and money each time the system fails, you don't mind so much. When it's your money, it somehow seems more important...

    I agree with you on the desirability of shared knowledge, but that seems to be hard to arrange in practice, and might not make much difference. Suppose you have half a dozen people with intimate knowledge of a particular system. Sooner or later, one of those people will leave, and their replacement will have to be brought up to speed. Since we all live on deadlines these days, this will usually be kept on the back burner until it's critical, ie, until someone notices that the last person who understands the system is leaving next week.
  • hatterson 2010-10-06 13:47
    TheJasper:
    Mick T:
    BA:
    As a Business Analyst...


    Uh oh...


    Lets set the mood early by revealing our prejudices.

    Mick T:

    BA:

    1) The volume of documentation should be function of the complexity, not the size of what is being developed.


    I think this completely misses the point...


    I think you need to look up what complexity is. If you are going to bash someone about is use of complexity you should be exact. There are many different types of complexity and for most people its about how many parts is has.


    This is correct. There is a large difference between complexity of logic (programs that do advanced statistical calculations as an example) and complexity of application (lots of various functions, although all simple)

    TheJasper:
    Mick T:

    BA:

    2) ALL documents should be tied to a specific version/release of the software. Each successive version then gets a new version of the document, with the ability to track all the changes that came through.


    You have to be kidding. So your solution to document complexity is to raise to the power the number of documents in existence?

    Who is going to do this and where are they going to get the time? Who is going to manage this process to make sure it happens? Who is going to allocate their budget for all of this to happen? And most importantly, how many different documents are people expected to wade through in order to gain even a partial understanding of your system?


    Actually this is a good idea. If you are going to document then tie it to the version. Otherwise don't document. This has nothing to do with the amount of documentation. As to who is supposed to do it? Depends on the doc but I don't accept lazy programmers who think documentation is beneath them.


    In an ideal world (read: unlimited time and resources) documentation would be exactly like that. A full set for each individual program version. However in the real world this simply isn't possible. Saying you don't accept "lazy programmers" doesn't solve the issue. Many times it's not a matter of level of effort but rather direction of effort. Does my boss want me to have detailed documentation that is kept up to date with every version or does he want me to fix twice the number of bugs in a given amount of time? In the vast vast majority of organizations, #2 is the option that is chosen.
  • North Shore Beach Bum 2010-10-06 13:54
    Chris Cowdery:
    You will find me poring over my code, not pouring.....

    Chris.


    I don't know - lots of code drives programmers to drinking.
  • boog 2010-10-06 13:54
    Jay:
    Just because you don't like the Bible is no reason to get irrational about it.

    No, but a needless reference to the bible in order to validate the word broil seems like a great reason to be irrational.

    Seriously, it's broil. BROIL. What rational person doesn't reference a cookbook first?
    </rant>
  • Anon 2010-10-06 14:34

    A 8’ length of 2” x 4” is just that, less planning

    Several people have made the comment that a 2x4 is not actually 2"x4". They all assumed he was talking about a piece of manufactured lumber. I don't see anything that specifically mentions some kind of wood product. He could have been talking about a 2"x4" piece of steel.

    This only proves the second point of that section:

    The human brain is somewhat understood, and will require lots of time and knowledge to fully understand

    You read the same thing I read, but your brain added a piece of information that wasn't actually there.
  • hatterson 2010-10-06 14:44
    boog:
    Jay:
    Just because you don't like the Bible is no reason to get irrational about it.

    No, but a needless reference to the bible in order to validate the word broil seems like a great reason to be irrational.

    Seriously, it's broil. BROIL. What rational person doesn't reference a cookbook first?
    </rant>


    Well the Bible is vastly more widely published than any other book and is also one of oldest books still being published in many languages. A cookbook may well have been a typed out version of the notes your mother kept in kitchen when you were growing up and might contain any variety of words whose admittance into the English languages is iffy at best.

    I'm not saying the original argument is a great one, but if you're referencing a book to show that a word is part of a given language (especially English), it's hard to justify a better choice than the Bible, regardless of your thoughts on it's spiritual or historical accuracy.
  • Adam 2010-10-06 14:56
    If you are going to write anything in depth, spend it on the specs up front for a better return on investment.

    Documentation that says what the system is supposed to do is far more useful to me than documentation that says what it actually does.

    My backup plan for missing docs is the code, but there is no backup plan for missing specs.






  • hatterson 2010-10-06 15:09
    imgx64:
    TRWTF is that TDWTF turned into a programmer's blog. I read the whole bloody thing waiting for the punchline. *sigh*


    Alex does these every so often. I remember one on patters of failure from a few months back. Last year there was a good one on the Cravath system too.

    I don't mind it from time to time, a nice change of pace.
  • Way2trivial 2010-10-06 15:32
    See what happens when developers reach outside their ken?

    a 2X4 is 1.5" X 3.5"


    you need a better analogy, how about a yardstick is 36 inches?
    that'll work, if you are inside the US

  • boog 2010-10-06 16:13
    hatterson:
    ...regardless of your thoughts on it's spiritual or historical accuracy.

    Nobody said anything about spiritual or historical accuracy. I was just ranting a silly rant about the needless shift of discussion.

    Or are you trolling for a religious debate on an IT-related website? Oh wait, I don't care.
  • sino 2010-10-06 16:20
    Anonymous:
    Design documentation is outside of my remit but I do my bit at the code level by enforcing code commenting standards throughout my company. I have Sandcastle set up to generate MSDN-style HTML pages for every code file in our codebase. This gets executed as part of our nightly automated builds and the output gets dumped onto a central server. This means that everyone in the company is just a hyperlink away from an up-to-date specification of the entire codebase.

    I have to admit that this only works because I'm so aggressive at getting people to follow the commenting standards (that I wrote). They know I review the comment coverage every week and will raise PRs for them to update any code that is not perfectly commented. We don't even do formal reviews of the actual code but I still review the comments evey week to make sure they are up to scratch. Very often, the comments are better written than the actual code.

    Despite all this, I'm pretty sure nobody reads the generated HTML spec except me. But as they say, you can lead a horse to water...
    TopCoder? Oh, please, say you brought Bozarking and Swampy back with you?

    *tear of joy*
  • ideo 2010-10-06 16:30
    catgull:
    Don't you mean do***entation?
    You're doing it wrong.

    The definitive example is "clbuttic", therefore the word should be dosemenentation.
  • ideo 2010-10-06 16:32
    Peter S. Conrad:
    Conciseness is crucial.
    Concision is key.
  • H.P. Lovecraft 2010-10-06 16:41
    I love how everyone comments on Alex's usage of the 2x4 but fails to notice that he mentions 'less planning' which I'm sure translates to 'less planing' and means *is 2x4, then planed'. Hence 1.5x3.5 ... of course drying comes into play to end up with the final measurement.

    He was right for the most part, if you correct the errant spelling.

  • ideo 2010-10-06 16:54
    boog:
    Jay:
    Just because you don't like the Bible is no reason to get irrational about it.

    No, but a needless reference to the bible in order to validate the word broil seems like a great reason to be irrational.

    Seriously, it's broil. BROIL. What rational person doesn't reference a cookbook first?
    </rant>
    Lol, I thought that's what the bible was!
    See: http://www.cookingwiththebible.com/results.aspx?option=all&q=all

    Also, calm down. Seriously. Reading religious texts is how you make atheists. Most "religious" folk have never even read their own scripture, let alone anyone else's.
  • Monica Lewinsky 2010-10-06 17:04
    History Lesson:
    3 Weeks Ago on Thursday: No TDWTF
    2 Weeks Ago on Monday: No TDWTF
    1 Week Ago on Tuesday: No TDWTF
    This Week on Wednesday: No TDWTF


    So next week, no TDWTF on Friday. Got it.

    Captcha: similis - Simian syphilis
  • drachenstern 2010-10-06 17:27
    imgx64:
    TRWTF is that TDWTF turned into a programmer's blog. I read the whole bloody thing waiting for the punchline. *sigh*
    Try this link ... http://thedailywtf.com/Series/Alex_0x27_s_Soapbox.aspx

    why does akismet think this is spam?
  • Nu Kua 2010-10-06 21:59
    This motivated me to finally sign up so I can comment with a stable identity.

    I generally agree with this article, and I completely agree with the overall philosophy. But I think there's one very important type left out: domain documentation.

    I write and maintain programs to support a domain that programmers inherently know next to nothing about, in an industry programmers inherently know absolutely nothing about. I've found the most useful documentation I can produce is some which describes the processes that my programs are trying to support.

    The single most useful document I have ever written is probably my glossary of industry jargon. I can verify that most of my co-workers have never gone anywhere near my attempts to document my library code, but I see every new programmer we hire keeping that glossary handy for their first few weeks.
  • frits 2010-10-06 23:17
    Nu Kua:
    This motivated me to finally sign up so I can comment with a stable identity.

    I generally agree with this article, and I completely agree with the overall philosophy. But I think there's one very important type left out: domain documentation.

    I write and maintain programs to support a domain that programmers inherently know next to nothing about, in an industry programmers inherently know absolutely nothing about. I've found the most useful documentation I can produce is some which describes the processes that my programs are trying to support.

    The single most useful document I have ever written is probably my glossary of industry jargon. I can verify that most of my co-workers have never gone anywhere near my attempts to document my library code, but I see every new programmer we hire keeping that glossary handy for their first few weeks.


    That actually sounds super useful. Thanks for sharing.
  • da Doctah 2010-10-07 00:17
    ideo:
    Peter S. Conrad:
    Conciseness is crucial.
    Concision is key.

    Short r00lz.
  • Ben 2010-10-07 02:48
    da Doctah:
    ideo:
    Peter S. Conrad:
    Conciseness is crucial.
    Concision is key.

    Short r00lz.


    !
  • Jeremy 2010-10-07 03:48
    mainframe_guy:

    Best part of the article:

    The ease of extracting and understanding these specifications varies on the complexity of the subject at hand.

    * A 8’ length of 2” x 4” is just that, less planning

    And this sums up the end problem. A two-by-four isn't actually 2" by 4". Hence, there is still ambiguity in the sentence above. This is the proof that documentation (less is more) is hard to write.

    and
    (Another) Jeremy:

    I'm amused that you picked a 2x4 as an "obvious" example. It is not obvious to someone who has never worked with wood before that a 2x4 is not actually 2" by 4", but 1.5" by 3.5". So much for idiot-proof specifications.


    Plus, of course, nowhere is it actually specified that this is describing a piece of wood.
  • Jeremy 2010-10-07 03:59
    frits:

    TheJasper:

    How do you ask a developer for clarification if he just got hit by a bus?

    The old hit-by-a-bus analogy rears its head. Why can't it be "What if the developer quits suddenly and moves to Katmandu?"??

    Because it's more fun to imagine our colleagues run down by a number 19 than to imagine them upping stumps and moving to Nepal.

    And "bus number" is a catchier way to talk about it than "Buddhist epiphany number".
    frits:
    What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?

    I'm not sure it's that specific risk that's being managed, but rather the more general (and hence somewhat higher) risk of someone with critical knowledge becoming suddenly and unexpectedly unavailable.

    And as long as it's a conscious decision, ignoring that risk is a perfectly valid way to manage it.
  • Jeremy 2010-10-07 04:10
    Jeremy:

    Plus, of course, nowhere is it actually specified that this is describing a piece of wood.

    As kindly pointed out by Anon in #324303.
  • Shinobu 2010-10-07 06:12
    I have several issues with Alex's text.
    Firstly, if you need to do database documentation you're not using the right tool for the job. Good database management systems allow you to view and edit your table relationships and descriptions in the database management interface itself, which in practice more or less guarantees it stays up-to-date.
    Secondly, the implication that the program itself can substitute for documentation, however clumsy, is flawed. Software contains bugs and hard decisions. When the program doesn't do what it should do, it cannot be used as documentation. When a program does something counter-intuitive future coders will be tempted to ‘fix’ it, so some documentation will be necessary to prevent that, often in the form of a comment, but sometimes a comment simply will not do, for example when it has something to do with the architecture of the program.
    Thirdly, as someone who sometimes has to jump head-first into code, I find the worst annoyance the total lack of general design documentation. You know, things like how classes relate, what the general control flow is, what happens when WM_RANDI gets handled (substitute whatever the program does fairly often). If you want to fix or replace something, you don't want to first pore through msrvr.cpp, mclnt.cpp, mappmain.cpp, mapp.cpp, widgetbase.cpp, ... on the hunt for the right class or method. Yet, such documentation is often completely absent, and some of the kinds of documentation that are most valuable here are exactly the kind of stuff that Alex tells us to let rot.
    In that spirit, let me highlight what may be the best post in the entire thread:
    ∃ Style.:
    This is the first time I read about this, and although it is highly indebted to ideas by Ken Perlin, I think that software is a wonderful application of the principle. This needs to be in every IDE.
  • Cbuttius 2010-10-07 07:46
    Kuba:
    I don't know what you imply by "practical" vs. "perfect", but the C++ FAQ discusses simply one of a widely misunderstood issues in OO programming as implemented in C++.

    The circle-is-an-ellipse is basically a very poorly thought out OO example that some half-wit put in a textbook one time, and it ended up being perpetuated ad nauseam. It simply does not fit within the C++ type system.


    A practical example of where the system fails only when you can modify is a collection of derived-class objects not being a type of collection of base-class objects.

    If you can't modify it then you can substitute anywhere, but if you can modify it then you could add invalid objects to the collection of base-class
  • Critical Mass 2010-10-07 08:34
    Wrong. The only thing important about documentation is consistency. You know, like actually doing daily postings to a site called "The Daily"...
  • Alan 2010-10-07 10:37
    Jay:

    One of the biggest time-wasters in many organizations I've worked in is the requirement that documents be kept updated after their useful life has ended. I've had many times when I was required to update a systems design document after programming was complete to reflect any changes made in the course of development, when I knew full well that now that development was complete, no one was ever going to look at these documents again. It reminds me of the joke of the aspring writer who is told by a publisher, "Your submissions are so bad, we have to rewrite them before we throw them away." Why update something just before filing it in the Black Hole Archive?


    I know exactly what you mean. It can be time-consuming and tedious to keep software documentation up-to-date and can sometimes seem fruitless if it is potentially never going to get used.

    We developed Code Rocket to provide automated documentation based on the code and comments around it - so it never gets out of date because you can just generate it again from the code. Being automated, you can produce documentation only when you need it... Check it out if you are interested - there is a free trial available.

    Thanks Alex for the great article.
  • ∃ Style. 2010-10-07 10:41
    Shinobu:
    This is the first time I read about this, and although it is highly indebted to ideas by Ken Perlin, I think that software is a wonderful application of the principle. This needs to be in every IDE.


    I first read on this on Lambda the ultimate (a blog you should read!). In the comments to the post you'll also see a reference to a code bubbles post which is somewhat related and also very interesting IDE wise ...
  • Python Fan 2010-10-07 13:11
    Cue *diabolical* laughter and intense musical chord.

    FTFY

    CAPTCHA acsi: character set for dyslexics
  • h1ppie 2010-10-07 16:14
    Jay:
    I don't know if less planning on your 2x4's is really a good idea. Surely we should always do good planning on carpentry products. If you cut a board wrong, you have to throw it away and get another. I think you meant "less planing".


    I believe the saying is: Measure twice, cut once.
  • Monica Lewinsky 2010-10-07 17:55
    Critical Mass:
    Wrong. The only thing important about documentation is consistency. You know, like actually doing daily postings to a site called "The Daily"...


    internets++
  • Bruce Hoges 2010-10-08 05:29
    fermion:
    In Australia we grill...

    Grill

    Cooking meat (or other food) directly under (as in a gas or electric oven) or over the heat source (as on a grill). Moisture is held in the food by the high cooking temperatures which quickly "seal in" flavour. This cooking method is ideal for tender cuts of meat.

    Barbecue

    Cooking food on a rack or plate over direct heat in a charcoal or gas barbecue or over hot coals.


    maaate, in 'strya we barbie - you sound like a pommie baastard
  • Strop 2010-10-08 05:33
    Bruce Hoges:

    maaate, in 'strya we barbie - you sound like a pommie baastard


    In 'straya we barbie as well. I didn't realise it was quite so popular over there in Austria.
  • madjo 2010-10-08 06:56
    frits:
    Is it too much to ask the developer for clarification? Does your company's management allow the testers to direct developer effort? There is not always going to be enough time to get both the code and the docuemntation correct. I'll take correct code over documentation any day.

    In agile environment (where I work in) there is time to get documentation done right. The way to do it, is to have the designers one iteration ahead from the developers. As testing can only be done when coding is complete.
    And I don't want to solely trust on the developers word on how a product must work. If I could do that, I wouldn't need to test.
    I'd get answers like "Yes, such and such is supposed to work like that" with every bug I find. Actually, I'd only have suspicions of bugs, as I don't know exactly how a product is supposed to work.
    The infamous "Feature, not bug" argument.
  • madjo 2010-10-08 07:04
    frits:
    wtf:
    frits:
    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

    "What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?"


    Okay, here's one answer:
    On my current job, I am documenting systems and processes for a medium-sized financial services company that you've never heard of. I don't have anything to do with the company's products, I'm just dealing with internal stuff, including HR, the website, the phone system, the data warehouse, and so forth. A large part of the justification for my position is summed up as "continuity of business". Continuity of business is the "developer leaves with <= 2 weeks notice" scenario, whether you call it "hit by a bus" or "moved to Kathmandu" or "got another job that paid more".
    I started at this position in March of last year. By June, two of the three developers whose work I was documenting had taken job offers at other companies, and left.

    Yes, it's worth the cost of managing that risk, because it's not a risk. It's a certainty: everybody leaves an organization at some point, and that is almost always done with two weeks or less of warning. The only thing you don't know is when this will happen. When they go, they take all of that stuff in their head and they walk out the door with it.


    If one person has all the knowledge, you're managing things wrong. Proper teaming and sharing of the work can mitigate this risk. If developers can do each other's jobs, then the risk is everyone leaving at once--like I said originally.

    BTW- I would like to have someone document my code for me. How can I convince my manager to provide this?

    It SHOULD be the other way around.
    You should be coding what is documented.
    We don't mean comments in code, we mean use case documents, business specs, message format specs, screen designs. All that stuff.
  • dan 2010-10-08 11:43
    Completely accurate & detailed documentaion is completely useless... it's just the program.

    http://en.wikipedia.org/wiki/Map%E2%80%93territory_relation


    Another basic quandary is the problem of accuracy. In "On Exactitude in Science", Jorge Luis Borges describes the tragic uselessness of the perfectly accurate, one-to-one map:

    In time, those Unconscionable Maps no longer satisfied, and the Cartographers Guild drew a Map of the Empire whose size was that of the Empire, coinciding point for point with it. The following Generations, who were not so fond of the Study of Cartography saw the vast Map to be Useless and permitted it to decay and fray under the Sun and winters.

    In the Deserts of the West, still today, there are Tattered Ruins of the Map, inhabited by Animals and Beggars; and in all the Land there is no other Relic of the Disciplines of Geography.
  • Mike 2010-10-08 15:01
    Or, from Getting Real:

    http://gettingreal.37signals.com/ch11_Theres_Nothing_Functional_about_a_Functional_Spec.php

    and

    http://gettingreal.37signals.com/ch11_Dont_Do_Dead_Documents.php
  • Josh 2010-10-08 23:56
    Jay:
    3. Help someone to formulate his thoughts.


    Exactly. No, no one except you may ever look at the Databse Table Design sheet again. But writing the Database Table Design sheet forces you to put some hard thought into the design of your database tables. Likewise, the Requirements list forces you to decide what your project's requirements are. Some documentation is for the benefit of those reading it, while other documentation is for the benefit of those writing it.
  • Captain Oblivious 2010-10-10 01:58
    Why are you talking about this so much? Documentation is EASY.

    1) Take the spec, and paste it into your source file.
    2) Break the spec up into steps, and put newlines between the steps.
    3) Put the implementation in the newly created space.
    4) Use some nice mathematical techniques, such as abstract interpretation, to make sure the function meets spec.
    5) Move on, and leave work as soon as you are done.
  • Roger Parkinson 2010-10-10 08:03
    One other class of documentation worth keeping up to date is the instructions on how to set up the dev environment. The worst cases have a ton of 'secret scripts' that every new developer has to waste time finding out about. Builds should be standard, of course, but that doesn't mean they are.
  • "religious" folk 2010-10-10 20:01
    ideo:
    Also, calm down. Seriously. Reading religious texts is how you make atheists. Most "religious" folk have never even read their own scripture, let alone anyone else's.

    I've read the Bible from cover to cover 6 times and I certainly haven't converted to atheism. If anything it gave me context of why stuff happened. e.g. people say "Why did God slaughter a town full of people?" and then you see in another part that maybe it was because the people were all butt raping their livestock and burning their children in fire to molech! In that context it seems fair. After all, Americans are still ok with the death sentence for these types of heinous crimes.
  • Jim 2010-10-11 06:37
    TheJasper:
    If you just start reading in the middle of the code everything may seem like a grain of sand. You don't start a book in the middle either.


    Seriously?! You've got a manager dogging your heels to finish off defect fix #1 today cause you have to start on defect fix #2 (on a different system) tomorrow and defect fix #3 (on a 3rd system) and you tell them, "Sorry, but I have to finish reading 1000s of lines of source code"
  • Anonymous 2010-10-11 10:27
    "religious" folk:
    ideo:
    Also, calm down. Seriously. Reading religious texts is how you make atheists. Most "religious" folk have never even read their own scripture, let alone anyone else's.

    I've read the Bible from cover to cover 6 times and I certainly haven't converted to atheism. If anything it gave me context of why stuff happened. e.g. people say "Why did God slaughter a town full of people?" and then you see in another part that maybe it was because the people were all butt raping their livestock and burning their children in fire to molech! In that context it seems fair.

    No, actually, the deliberate deprivation of another's human rights does not seem fair in any context. To anyone apart from religious folk, that is. Oh, and serial killers. I'm sure that's just a coincidence though...
  • "religious" 2010-10-11 22:24
    Anonymous:
    No, actually, the deliberate deprivation of another's human rights does not seem fair in any context. To anyone apart from religious folk, that is. Oh, and serial killers. I'm sure that's just a coincidence though...

    So you don't believe that someone who burns their children in the fire deserves the death sentence?
  • boog 2010-10-12 13:01
    "religious":
    Anonymous:
    No, actually, the deliberate deprivation of another's human rights does not seem fair in any context. To anyone apart from religious folk, that is. Oh, and serial killers. I'm sure that's just a coincidence though...

    So you don't believe that someone who burns their children in the fire deserves the death sentence?

    Well, it's not fair to deprive another's human rights in any context, so no, it's technically not fair to give them the death sentence. At the same time, it's my personal opinion that if they factually did deprive the kids of their human rights by burning them (assuming they weren't set up, or had a legitimate reason, such as the kids were turning into zombies or something), feel free to throw a death sentence their way.

    Why can't we do it and still admit it's probably not ethical? Our society isn't perfect. I certainly hope that some day we can come up with a better solution than capital punishment, but first we have to stop bickering about it.

    Also, congrats on taking this even further off-topic, people. Capital punishment? I didn't see it going there.
  • Anonymous 2010-10-13 08:51
    "religious":
    Anonymous:
    No, actually, the deliberate deprivation of another's human rights does not seem fair in any context. To anyone apart from religious folk, that is. Oh, and serial killers. I'm sure that's just a coincidence though...

    So you don't believe that someone who burns their children in the fire deserves the death sentence?

    No I do not. I do not believe that capital punishment is an acceptable response to any crime, irrespective of the severity. That person could have raped their kids before burning them, I still wouldn't support the death penalty.
  • Mathias Weiersmueller 2010-10-15 07:46
    Clearly, executive visibility didn’t come cheap, and the barrage of required documentation was simply a tax. As I spent the next week pouring over the documentation templates, I couldn’t help but wonder who would ever find these useful. The more forms I filled out, the more I realized that the answer was no one. When I finally arrived at the “Database Table Design” document (which documents exactly what its title implies), I realized exactly what it was that I producing: write-only documentation.


    I had to smile about "write-only documentation" - so true!
    A lot of documentation was just written because the project required it to be compliant with ISO9001, CMMI, ITIL, <feel free to include any other buzzwords>. Or even worse, just in order to tick off the documentation requirement.

    The scope and the extent of the documentation should be already defined in a project plan:

    - What's is the intended audience? (users, developers, operations staff, managers)
    - Which knowledge level should be already present?
    - What purpose does the documentation(s) serve? ( Some ideas: "Help the user to use the application", "Help support staff to support the application", "Help developers to integrate the product into their system"). Help is the central word here!

    I work in an environment which supports 100s of applications - the support staff relies heavily on documentation as nobody will ever have a complete picture of the application landscape. Some general thoughts about how people can work efficiently with documentation:

    Organize documentation
    DONT: Just put all documentation in a shared folder.
    DO: Categorize documentation and provide a structured approach which reflects the use case. Check with the target audience how fast they find the information they need.

    Keep documentation up to date. Always.
    DONT: Introduce new releases and tell people that the documentation will be updated soon (read: never)
    DO: Realize that the documentation is an integral part of the application. A new release is only signed off when the documentation has been updated too. Think of automating documentation (we create network drawings automatically using homemade scripts)

    Assign responsibility to a Doc master.
    DO: Make somebody responsible for the accuracy of documentation.
    DO: Doc Master reviews documentation on regular basis.
    DO: when team members find a mismatch in the documentation, they forward the problem to the Doc Master. He is the problem owner.

    Make sure your documentation is usable
    DONT: assume that documentation is ok if you are finished
    DO: make sure there is somebody in the target audience who will check and sign-off the documentation. Ask questions like: do the docs help you to do your job? would you use the documentation? if not: why?


  • - 2010-10-18 11:57
    Strange that nobody mentioned it yet, but there's a significant error in the article.
    You can not understand any code. If we assume that human brain is a Turing-compatible machine, the Rice's theorem states:
    For every programmer ther's code they won't understand.
  • Jarrow 2010-12-29 23:49
    Clearly you've never had to deal with government or legal requirements. : )

    About 1/3rd of my job as a global projects technical architect has devolved to the production of insanity-inducing documentation as required by a phone-book sized batch of laws and regulations. For example, I have to follow Food and Drug Administration doc requirements intended for documenting design decisions for nuclear medicine and x-ray machines, simply to deploy email scanning appliances and laptop antivirus software.

    It got so bad, that the company instituted separate documentation processes - one for the regulatory work, and 'work instructions' for people who actually need to learn what it does. : )
  • Ralph 2011-01-23 02:28
    "Documentation is like sex: when it is good, it is very, very good; when it is bad, it is better than nothing." - Dick Brandon
  • Anon 2011-04-20 12:57
    Documentation should be threefold,

    1) Hit by a train documentation:- This is documenting what you were last working on so that someone less competent/not familiar with your code base can have a starting point. Usually called an issue tracker.

    2) Getting a better job documentation:- This is documentation in code that generates class diagrams so that everyone knows what your functions are supposed to do. Then you or anyone else can find leverage points to put their own code in to make new features/products. Usually use Doxygen, or other autogen docs generators.

    3) Thinking ahead documentation:- This is designing how things should roughly work before writing any code. So you know where you are going and not forced down crappy code paths. This generally is a pitfall of the "I'm good a building Lego I don't need no plan." type of programmer. Usually a whiteboard and marker, or paper and pen, or any other drawing combination.

    In the company I work for the 2 other developers do the following: 1) Never happens, why? "Issue tracker, whats an issue tracker? surly thats what excel is for." 2) Never happens, why? "Comments? they make the code difficult to read.", "Diagrams? what have they got to do with code?", and "My code is self documenting" 3) Never happens, why? "I am great with Lego!", and "look I drew a cock on the whiteboard!"

    For f*** sake they have a config file parser that is made up of 18 different dll, most with just 4 class in one c# file.

    I think it might be time for a new job...
  • Prism 2011-07-12 11:52
    RandomUser423695:
    Ajtacka:
    I think the translation is "grill".
    A quick dictionary check suggests "grill" is a specific form of "broiling". To broil is to expose the object to direct radiant heat regardless of source or position, while grilling (generally) requires a grill or griddle with the object (usually) above the heat source.


    I think I get it now!

    This type of off-topic banter regarding spelling or semantic details and the real meaning of words is like a running schtick here on TDWTF - isn't it? Isn't it?

    Its like a Abbot and Costello routine constantly running in the background in order to break our train of thought as we read the thread!

    And I'll bet, I'll just bet you guys AREN'T REALLY HUMAN AT ALL -- YOUR ALIEN CYBORGS WHO HAVE HACKED OUR INTERWEBS FROM OUTER SPACE AS PART OF YOUR PRE-INVASION PLAN TO BREAK OUR MORALE AND DRIVE US CRAZY!

    I knew it, I fuckin knew it! No way would humans do this to each other, no way.
  • ed 2014-08-12 09:43
    are you sure you work in IT?