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);'
--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--~~--

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.