• ideo (unregistered) in reply to Peter S. Conrad
    Peter S. Conrad:
    Conciseness is crucial.
    Concision is key.
  • H.P. Lovecraft (unregistered)

    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 (unregistered) in reply to boog
    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 (unregistered) in reply to History Lesson
    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

  • (cs) in reply to imgx64
    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?

  • (cs)

    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.

  • (cs) in reply to Nu Kua
    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.

  • (cs) in reply to ideo
    ideo:
    Peter S. Conrad:
    Conciseness is crucial.
    Concision is key.
    Short r00lz.
  • Ben (unregistered) in reply to da Doctah
    da Doctah:
    ideo:
    Peter S. Conrad:
    Conciseness is crucial.
    Concision is key.
    Short r00lz.

    !

  • Jeremy (unregistered) in reply to mainframe_guy
    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 (unregistered) in reply to frits
    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 (unregistered) in reply to Jeremy
    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 (unregistered) in reply to ∃ Style.

    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.

  • (cs) in reply to Kuba
    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 (unregistered)

    Wrong. The only thing important about documentation is consistency. You know, like actually doing daily postings to a site called "The Daily"...

  • Alan (unregistered) in reply to Jay
    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. (unregistered) in reply to Shinobu
    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 (unregistered) in reply to Rich

    Cue diabolical laughter and intense musical chord.

    FTFY

    CAPTCHA acsi: character set for dyslexics

  • h1ppie (unregistered) in reply to Jay
    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 (unregistered) in reply to Critical Mass
    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 (unregistered) in reply to fermion
    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 (unregistered) in reply to Bruce Hoges
    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.

  • (cs) in reply to frits
    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.
  • (cs) in reply to frits
    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 (unregistered)

    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 (unregistered)

    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 (unregistered) in reply to Jay
    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.

  • (cs)

    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 (unregistered)

    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 (unregistered) in reply to ideo
    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 (unregistered) in reply to TheJasper
    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 (unregistered) in reply to "religious" folk
    "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" (unregistered) in reply to Anonymous
    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?
  • (cs) in reply to "religious"
    "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 (unregistered) in reply to "religious"
    "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 (unregistered)
    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?

  • - (unregistered)

    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 (unregistered)

    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 (unregistered)

    "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 (unregistered)

    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 (unregistered) in reply to RandomUser423695
    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 (unregistered)

    are you sure you work in IT?

Leave a comment on “Documentation Done Right”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article