• (cs)

    Isn't that what Doxygen is there to do?

  • Rich (unregistered)

    (jumps into the scene) "Nobody expects the Source-Code Mismatch!"

    Cue laughter.

  • Anonymous (unregistered)

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

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

    TRWTF is VB

  • Anonymous (unregistered) in reply to SR
    SR:
    TRWTF is VB
    Off-topic but painfully true nonetheless.
  • (cs)

    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.

  • (cs)

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

    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.

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

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

    I have documentated your design. Pray I don't document it further.

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

    Hello from the third circle of hell! It's a very nice place, actually ;)

  • Tom7 (unregistered) in reply to Ajtacka

    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.

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

  • (cs) in reply to Steve The Cynic
    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.

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

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

    You will find me poring over my code, not pouring.....

    Chris.

  • (cs)

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

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

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

  • (cs) in reply to Chris Cowdery
    Chris Cowdery:
    You will find me poring over my code, not pouring.....

    Chris.

    you'll sometimes find me pouting over code...

  • bob (unregistered)

    "No amount of documentation will help the average developer understand brilliant systems..."

    The real WTF is that you misspelled "brillant."

  • (cs)

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

    UML? People actually use that in the real world?

    Nah, they don't. We know this.

  • Anonymous Coward (unregistered) in reply to Tom7
    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 (unregistered) in reply to Steve The Cynic
    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.

  • (cs)

    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

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

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

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

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

  • (cs) in reply to Mr. Can't bother to register
    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 (unregistered) in reply to Ajtacka

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

  • (cs)

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

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

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

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

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

  • (cs)

    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]".

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

    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 (unregistered) in reply to Rich
    Rich:
    (jumps into the scene) "Nobody expects the Source-Code Mismatch!"

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

    Sounds about right!

  • Jay (unregistered)

    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?

Leave a comment on “Documentation Done Right”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article