Until recently, I haven't written anything for real production use. A few beta apps, personal use shell scripts and such. Now I have a few things that I'm fixing to release, and good documentation will be needed. In viewing some other nodes about writing documentation, I'm sure I have a good idea of what I need to do, sum it up in a professional manner that is easy to understand. I have written HOW TO's and README's before, but never full fledged documentation. I'm sure your probably thinking; What is there to it? You write a useful documentation on what you did, and the functions of the program. However, IMHO, the art of writing good doc's to back up your work is as much of an art as the code itself.

What I really want to get from this post is your thoughts on writing good documentation. Stuff from this could be compiled to make a useful tutorial. So please hit me with your knowledge/opinions!

P.S. In addition to wanting to hear what you think about writing Doc's, I'd also like to hear what you think about a Tutorial on the subject.

--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--
perl -e '$a="3567"; $b=hex($a); printf("%2X\n",$a);'
--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--

In reply to Writing Good Documentation by defyance

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.