I think you missed a close font tag. :-) Excellent post. I have been saying this (to no avail) in my present team/company for a long time. All those people who think making developers document their own code is a good plan are nuts. My experience is that developers usually have several orders greater understanding than the user/management does of the systems they are working on and computers in general (no suprise here). What is a trivial matter not worth even mentioning to a developer can be a point of crucial misunderstanding leading to a show stopper for a user. To expect a developer to even be able to lower their mind to the level where they cover what needs to be covered with the detail appropriate for an end user is a great way to ensure your documents are unusable. Sure there are developers out there who can do this, but they aren't common.

This remind me of a story from my long distant past. I was doing some remedial mathematics and was having some problems with some stuff. So I went over to a see a good friend, who was at that time in the first or second year of his math PHD. He _tried_ to help me with my homework, but in the end we gave up. The reason was that he just couldnt forget his skills. One question was expected to result in around a page of sums, he stepped in and used some rule they dont teach you untile 2nd or 3rd year Math that reduced it to something like 2 lines. Of course this was no good to me. My point here is that expecting a developer to write documentation that is usable by a noncomputer expert is like asking my friend to forget all the math he had ever learned and to return to thinking along the same lines he did in high school. No chance.


---
demerphq

<Elian> And I do take a kind of perverse pleasure in having an OO assembly language...

In reply to Re: Re: requirement documents? by demerphq
in thread requirement documents? by LameNerd

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.