Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

Most good programmers write some really crappy documentation. And even if they do go to the trouble of writing documentation, there's the chance that it's not kept in sync with the actual code.

I would love to see 'Writing Documentation 101' taught as part of a computer science degree, but even if the programmer could manage to write something, it goes against just about everything most programmers hold valuable -- saving time.

We write tools to save ourselves time ... often, it's write once, and forget about it. Until you start getting into something that's cyclic in nature, with a rather long period (eg, you only have to do it once a year or so), you think to yourself that there's no point it documenting things. Come the third or fouth time of trying to remember what you were doing, you start to appreciate how important the documentation is ... but even then, you're writing documentation for yourself, and not for others.

Have you ever had a class, where the teacher wrote the book? If the teacher makes no sense in class, you read the book, and realize that it's all been presented in the same way that makes no sense to you. The only benefit of writing documentation is in forcing the programmer to think about things in a way to present it clearly.

Personally, I've been writing my interfaces before I write the programs lately -- you can write the general user documentation, make sure it plugs in with other programs that might make use of it, and then fill in the blanks. But I've gotten stung a few times by minor changes that I forgot to express in the docs, and when I look at it 6 months later, I have to remember why I made changes that broke the docs (I know, anything in the docs should be expressed as a test, so that the errors will show up when I run the text suite, and I need to set up the test suites to generate reports nightly, in case something gets committed by someone else to the repository)

Right ... so as I've gone off on a tangent -- what's the right solution? Hopefully, get someone else to write the docs, or to ask you enough questions early on, that you start answering them, and recording them as documentation. Writing the docs yourself does no good unless you then get someone to use the docs, and essentially test them to make sure that they don't confuse people.


In reply to Re^2: What sets Perl back by jhourcle
in thread What sets Perl back by gunzip

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, 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, 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.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others cooling their heels in the Monastery: (7)
    As of 2021-01-18 23:32 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      Notices?