• mainframe_guy (unregistered)

    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.

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

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

    Actually, an eight foot 2x4 is 3 1/2 inches wide by 1 1/2 inches thick. Go figure.

  • Anonymous Brave (unregistered)

    With this nonWTF I did as I do with most documentation... tl;dr

  • imgx64 (unregistered)

    TRWTF is that TDWTF turned into a programmer's blog. I read the whole bloody thing waiting for the punchline. sigh

  • Bert Glanstron (unregistered) 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*
    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 (unregistered) 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*
    The article type was "Alex's Soapbox"-- it was intended to read like a programmer's blog. Alex occasionally likes to pontificate.
  • Moshe (unregistered)
    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 (unregistered) in reply to Mike
    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 (unregistered) in reply to David
    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 (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.

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

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

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

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

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

    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 (unregistered) in reply to the old rang
    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 (unregistered) in reply to Jay
    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 (unregistered) in reply to Moshe
    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.
  • (cs)

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

    What's wrong with a recipe for salted water?

  • Herby (unregistered)

    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!

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

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

    Don't you mean do***entation?

  • BA (unregistered)

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

    Conciseness is crucial.

  • fermion (unregistered)

    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.

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

  • (cs)

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

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

  • (cs)

    Given infinity time and resources, who needs good documentation? Just study the code.

  • OldCoder (unregistered) in reply to The Compiler
    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) (unregistered)

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

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

    I was looking for a WTFstory, instead I find a small essay paper on writing documentation.

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

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

    "Of all people, I have a pretty high standard for doing things right."

    He's joking, right?

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

    How do you know what is correct code? How do you ask a developer for clarification if he just got hit by a bus?

Leave a comment on “Documentation Done Right”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article