• Slicerwizard (unregistered)

    "As I spent the next week pouring over the documentation templates"

    Like I was saying...

    I'm sure there are more eggcorns in this masterpiece.

  • (cs) in reply to OldCoder
    OldCoder:
    Captcha: abbas. Something to do with Sweden?

    Try chairman of the PLO and former PM of the PA. Either this forum is run by terrorists, you are a terrorist or all those people telling us to be scared of terrorists are terrorists. Either way I'm frightened.

  • (cs) in reply to TheJasper
    TheJasper:
    How do you know what is correct code?
    Correct code is code that works as intended and agreed to by the customer.
    TheJasper:
    How do you ask a developer for clarification if he just got hit by a bus?
    The old hit-by-a-bus analogy rears its head. Why can't it be "What if the developer quits suddenly and moves to Katmandu?"? What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?
  • itsmo (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.

    or this http://en.wikipedia.org/wiki/Grilling

  • itsmo (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 <b> planing </b>

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

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

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

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

    FTFY
  • Ben (unregistered)

    TRWTF is that your company's website has contact details in a background image, including "www.inedo.com". O RLY IS DAT TEH WEB ADDRESS I'M ON??

  • (cs) in reply to frits
    frits:
    TheJasper:
    How do you know what is correct code?
    Correct code is code that works as intended and agreed to by the customer.

    How do you know what was intended and agreed to?

    frits:
    TheJasper:
    How do you ask a developer for clarification if he just got hit by a bus?
    The old hit-by-a-bus analogy rears its head. Why can't it be "What if the developer quits suddenly and moves to Katmandu?"? What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?

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

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

  • (cs) in reply to Ben
    Ben:
    TRWTF is that your company's website has contact details in a background image, including "www.inedo.com". O RLY IS DAT TEH WEB ADDRESS I'M ON??

    Clearly you are not visiting the correct website if you believe the contact details are stored in a background image.

  • (cs) in reply to TheJasper
    TheJasper:
    frits:
    TheJasper:
    How do you know what is correct code?
    Correct code is code that works as intended and agreed to by the customer.

    How do you know what was intended and agreed to?

    frits:
    TheJasper:
    How do you ask a developer for clarification if he just got hit by a bus?
    The old hit-by-a-bus analogy rears its head. Why can't it be "What if the developer quits suddenly and moves to Katmandu?"? What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?

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

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

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

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

  • History Lesson (unregistered)

    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

  • (cs) in reply to frits
    frits:
    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

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

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

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

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

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

  • Bert Glanstron (unregistered) in reply to frits
    frits:
    TheJasper:
    frits:
    TheJasper:
    How do you know what is correct code?
    Correct code is code that works as intended and agreed to by the customer.

    How do you know what was intended and agreed to?

    frits:
    TheJasper:
    How do you ask a developer for clarification if he just got hit by a bus?
    The old hit-by-a-bus analogy rears its head. Why can't it be "What if the developer quits suddenly and moves to Katmandu?"? What's the likelihood of everyone with domain knowledge being hit by a bus? Is it worth the cost of managing that risk?

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

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

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

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

    You are an idiot and should be banned from your mommy and daddy's modem.
  • (cs) in reply to TheJasper
    TheJasper:
    frits:
    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

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

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

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

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

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

    Not to mention people you need may not be around for other reasons. They could be on location, work different hours, be on vacation... If I lose a day because I can't ask a Fred an important question until tomorrow then that is an expensive question.

  • JJ (unregistered)
    The Article:
    No amount of documentation will help the average developer understand brilliant systems like The Policy Entry System and The Customer-Friendly System.
    Am I really the first to point out that Alex misspelled "brillant"?
  • (cs) in reply to JJ
    JJ:
    The Article:
    No amount of documentation will help the average developer understand brilliant systems like The Policy Entry System and The Customer-Friendly System.
    Am I really the first to point out that Alex misspelled "brillant"?
    no
  • Jim (unregistered)

    I wonder if the reason the project management team asked for the database table design was because programmers would just start coding without thinking things through first. At least this way they would be forced to stop and write something

  • Anonymous (unregistered) in reply to Jim
    Jim:
    I wonder if the reason the project management team asked for the database table design was because programmers would just start coding without thinking things through first. At least this way they would be forced to stop and write something
    This isn't a problem that's solved by documentation - this is a problem that's solved by hiring good programmers. If you don't trust your own staff enough to let them get on with the job then you need to improve your hiring practices. Better to hire good staff than to force pointless write-only documentation onto the team.
  • Max (unregistered) in reply to frits
    TheJasper:
    frits:
    TheJasper:
    How do you know what is correct code?
    Correct code is code that works as intended and agreed to by the customer.

    How do you know what was intended and agreed to?

    If you get paid
  • (cs) in reply to Anonymous
    Anonymous:
    Jim:
    I wonder if the reason the project management team asked for the database table design was because programmers would just start coding without thinking things through first. At least this way they would be forced to stop and write something
    This isn't a problem that's solved by documentation - this is a problem that's solved by hiring good programmers. If you don't trust your own staff enough to let them get on with the job then you need to improve your hiring practices. Better to hire good staff than to force pointless write-only documentation onto the team.

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

    Forcing pointless documentation will still be pointless in any situation. The point is documentation isn't always pointless. Forcing a particular form of documentation is also a way of making room in the process. If you don't ask for it you may also be cutting into valuable design time. Let's not forget that a bug in production is massively more expensive than one in development.

  • Anonymous Nitpicker (unregistered)
    which documentation is to be maintained and which is to be archived (i.e., read-only and left to rot).
    itym "write-only"
  • (cs) in reply to TheJasper
    TheJasper:
    You didn't address my question either, you avoided it. Your 'comment' about why can't it be 'moved to katmandu' implied you saw those as separate cases which needed to be addressed first.
    If you say so. My comment was a humorous observation about the "hit-by-a-bus" cliche. It's morbid. Why can't we use a different one?
    TheJasper:
    Generally speaking you want to avoid having a person who is the only source for some information.
    I never said or implied this. Of course nobody wants this situation. See Strawman.
  • (cs) in reply to Max
    Max:
    TheJasper:
    How do you know what was intended and agreed to?
    If you get paid

    Good luck with that strategy. Repeat customers tell you are doing something right. Getting paid means they either can't or don't want to make an issue out of something. Not to mention the amount of poorly written contracts where regardless of what is or isn't delivered payment will have to be made.

  • boog (unregistered) in reply to TheJasper
    TheJasper:
    How do you know what was intended and agreed to?
    Requirements analysis, acceptance testing, customer-signoff, etc. There are ways.

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

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

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

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

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

  • (cs) in reply to frits
    frits:
    If you say so. My comment was a humorous observation about the "hit-by-a-bus" cliche. It's morbid. Why can't we use a different one?

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

    TheJasper:
    Generally speaking you want to avoid having a person who is the only source for some information
    frits:
    I never said or implied this. Of course nobody wants this situation. See Strawman.

    Not a strawman. It's part of the whole point of documentation. Also, you did imply this by saying you could just ask the developer for clarification. Either way it's a situation which happens all too often and can be alleviated by documentation. Not by useless documentation, but by relevant documentation.

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

    You forgot: This Week on Tuesday: No TDWTF

  • x-sol (unregistered)

    Having long ago worked in food services let me help out here.

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

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

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

    but then I do work with Paulla the brillant

  • (cs) in reply to x-sol
    x-sol:
    Having long ago worked in food services let me help out here.

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

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

    I agree with your definition, but then nobody said anything about "BBQ". The reference was to "barbecue", which is unrelated.

  • boog (unregistered) in reply to Anonymous Nitpicker

    I think he meant just what he said, "read-only," as in once you archive it you never modify it again. "Write-only" implies that it won't be a useful reference later, which is not necessarily the case.

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

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

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

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

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

  • wtf (unregistered) in reply to frits
    frits:
    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

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

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

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

  • wtf (unregistered) in reply to JJ
    JJ:
    The Article:
    No amount of documentation will help the average developer understand brilliant systems like The Policy Entry System and The Customer-Friendly System.
    Am I really the first to point out that Alex misspelled "brillant"?

    No.

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

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

    I don't know what you imply by "practical" vs. "perfect", but the C++ FAQ discusses simply one of a widely misunderstood issues in OO programming as implemented in C++.

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

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

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

    Suppose you're designing a 2D computational geometry system -- whatever you code for an Ellipse is just generalization of code that would deal with a Circle, so the Circle class becomes a premature optimization. If profiling shows that whatever code simplification is afforded by a circular Ellipse is worth it, then you can insert the requisite r1==r2 tests into the code that deals with Ellipses, as a profile-guided optimization.

  • fool (unregistered)

    The purpose of software documentation is to be an encyclopedia to the world that is the program or system. It should be a reference work that is useful to (a) new people who need to get up to speed on the basic concepts, and be shown some places to get started using or maintaining it, and (b) people trying to troubleshoot a problem or find out how to do something that the software does or that they think that the software might do but aren't sure whether it does and if so what it's called and how to do it. It should't be written in terms of itself. That is, jargon and new concepts need to be explained, not just thrown around. It should be written with awareness that things will change over time. Don't just ignore how things used to work, assuming that everyone is doing the new thing now; don't write about option x1 as if it is the only option or way to do Function X, or the person trying to get x2 to work will be really confused. It should be terse, but not an incomplete thing that pretends to be complete. For gods sake, that last point, if nothing else.... if not, or if it's just not going to be accurate or maintained, just delete it and do everyone a favor!

  • (cs) in reply to Jay
    Jay:
    Anonymous Coward:
    Tom7:
    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.
    Instead of fairy tales, you'd be better off checking a dictionary:

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

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

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

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

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

    You assume that Bible translators weren't mistaken in their understanding of biblical languages, nor of their contemporary ones! Besides, the GP said nothing about broil not being a word -- so I don't see the point of your rant. The GP said that a word's definition should be looked up in the dictionary, not inferred from a text whose meaning is often vague by itself and subject to preconditioned thinking. You can't depend on Bible for circular-reference-definition of language.

  • (cs) in reply to TheJasper
    TheJasper:
    OldCoder:
    Captcha: abbas. Something to do with Sweden?

    Try chairman of the PLO and former PM of the PA. Either this forum is run by terrorists, you are a terrorist or all those people telling us to be scared of terrorists are terrorists. Either way I'm frightened.

    Abbas is a seafood company in Sweden. I like their red smoked roe paste -- got a taste for it as a kid visiting Sweden, now I pay regular visits to Ikea to get my fix.

  • (cs) in reply to wtf
    wtf:
    frits:
    Enough with the circular arguments, strawmen, and cherry picking. Sheesh. Why didn't you address this question:

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

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

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

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

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

  • The Bytemaster (unregistered) in reply to Jay
    Jay:
    Anonymous Coward:
    Tom7:
    'Broiled' is in Luke 24:42, Authorised & American Standard versions. I think it's in the language.
    Instead of fairy tales, you'd be better off checking a dictionary:

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

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

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

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

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

    You forgot to mention that it is also a translation to english making word usage very relevent - even more so considering how many copies are made, read, etc.

  • ∃ Style. (unregistered)
  • wtf (unregistered) in reply to frits
    frits:
    BTW- I would like to have someone document my code for me. How can I convince my manager to provide this?

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

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

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

  • (cs) in reply to TheJasper
    TheJasper:
    Mick T:
    BA:
    As a Business Analyst...

    Uh oh...

    Lets set the mood early by revealing our prejudices.

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

    I think this completely misses the point...

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

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

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

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

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

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

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

  • North Shore Beach Bum (unregistered) in reply to Chris Cowdery
    Chris Cowdery:
    You will find me poring over my code, not pouring.....

    Chris.

    I don't know - lots of code drives programmers to drinking.

  • boog (unregistered) in reply to Jay
    Jay:
    Just because you don't like the Bible is no reason to get irrational about it.
    No, but a needless reference to the bible in order to validate the word broil seems like a great reason to be irrational.

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

  • Anon (unregistered)
    A 8’ length of 2” x 4” is just that, less planning
    Several people have made the comment that a 2x4 is not actually 2"x4". They all assumed he was talking about a piece of manufactured lumber. I don't see anything that specifically mentions some kind of wood product. He could have been talking about a 2"x4" piece of steel.

    This only proves the second point of that section:

    The human brain is somewhat understood, and will require lots of time and knowledge to fully understand
    You read the same thing I read, but your brain added a piece of information that wasn't actually there.
  • (cs) 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>

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

    I'm not saying the original argument is a great one, but if you're referencing a book to show that a word is part of a given language (especially English), it's hard to justify a better choice than the Bible, regardless of your thoughts on it's spiritual or historical accuracy.

  • Adam (unregistered)

    If you are going to write anything in depth, spend it on the specs up front for a better return on investment.

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

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

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

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

    I don't mind it from time to time, a nice change of pace.

  • Way2trivial (unregistered)

    See what happens when developers reach outside their ken?

    a 2X4 is 1.5" X 3.5"

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

  • boog (unregistered) in reply to hatterson
    hatterson:
    ...regardless of your thoughts on it's spiritual or historical accuracy.
    Nobody said anything about spiritual or historical accuracy. I was just ranting a silly rant about the needless shift of discussion.

    Or are you trolling for a religious debate on an IT-related website? Oh wait, I don't care.

  • sino (unregistered) in reply to Anonymous
    Anonymous:
    Design documentation is outside of my remit but I do my bit at the code level by enforcing code commenting standards throughout my company. I have Sandcastle set up to generate MSDN-style HTML pages for every code file in our codebase. This gets executed as part of our nightly automated builds and the output gets dumped onto a central server. This means that everyone in the company is just a hyperlink away from an up-to-date specification of the entire codebase.

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

    Despite all this, I'm pretty sure nobody reads the generated HTML spec except me. But as they say, you can lead a horse to water...

    TopCoder? Oh, please, say you brought Bozarking and Swampy back with you?

    tear of joy

  • ideo (unregistered) in reply to catgull
    catgull:
    Don't you mean do***entation?
    You're doing it wrong.

    The definitive example is "clbuttic", therefore the word should be dosemenentation.

Leave a comment on “Documentation Done Right”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article