Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation

comment on

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

The first is that one way to document is to strive to make as little as possible worth documenting. What do I mean by that? Well suppose you write a script, and it has a bunch of dependencies. What is good is if you can make it have as few installation dependencies as possible, and make those as clear as possible. Then you don't have very much to document about how to install it!

The second is to consider ways of combining user documentation and specs. An extreme is the approach that Microsoft has been known to take, of actually writing the user documentation as a spec. Somewhat less extreme is the approach of writing down "use cases" for a spec (this is advocated by extreme programming, among other schools). When you have done that, the use cases are extremely suggestive about what to put into the user documentation.

In reply to Re (tilly) 1: How to write documentation? by tilly
in thread How to write documentation? by ajt

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

  • 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 or How to display code and escape characters are good places to start.
Log In?

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

How do I use this? | Other CB clients
Other Users?
Others wandering the Monastery: (1)
As of 2021-11-30 09:27 GMT
Find Nodes?
    Voting Booth?

    No recent polls found