Beefy Boxes and Bandwidth Generously Provided by pair Networks
laziness, impatience, and hubris

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
Documentation comes in two flavors - developer docs and user docs. For library-type code, like CGI or DBI, they may be more similar than, say, for Template or Mason.

User docs are the easy one, conceptually. You need to do something similar to Microsoft's helpfiles. Whatever you may feel about their products or practices, they are really good in their docs, for the average user.

Developer docs are more specific. I would want to know the following:

  • What requirements does this satisfy?
  • What were the architecture choices? Why was this one chosen?
  • What is the API? If possible, who uses the API? How much of the API is inviolable?
  • What are the assumptions? Preconditions and postconditions are an excellent way of putting it.
  • What were the implementation choices? What was this one chosen?
  • Most importantly, where are you going with this? What are the intended future directions? Why?
  • What tests does this pass? How are the tests run? How often?
  • What is the build process? How is the build run? How often?

These are all the same questions you would ask if you were handed 1200 lines of code and told "Make XYZ changes to it".

Being right, does not endow the right to be rude; politeness costs nothing.
Being unknowing, is not the same as being stupid.
Expressing a contrary opinion, whether to the individual or the group, is more often a sign of deeper thought than of cantankerous belligerence.
Do not mistake your goals as the only goals; your opinion as the only opinion; your confidence as correctness. Saying you know better is not the same as explaining you know better.

In reply to Re: Preferred method of documentation? by dragonchild
in thread Preferred method of documentation? by Anonymous Monk

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?

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

    How do I use this? | Other CB clients
    Other Users?
    Others wandering the Monastery: (3)
    As of 2020-11-26 03:09 GMT
    Find Nodes?
      Voting Booth?

      No recent polls found