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

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
These may look like generalist issues, but they're really a list of gripes I've had about documentation I was trying to depend on, as well as on documentation I've participated in creating :)

  • Carefully choose the viewpoint from which you write. In practice, this means to me that it's important to inspect what you assume from your readers. Who's the audience? etc. In my experience, docs assuming a relatively extreme tech reader usually fails, since no two readers have the same education or experience. It's also dangerous to assume that the author's education is the standard the docs are written to as well.

    Not that I think it should pander to illiterates or uneducated, but I think there are ways to make docs plainly readable, and understandable, for just about everyone.

  • Regardless of the the assumed audience, compose in readable, possibly Reader's Digest style, language. I know that'll get me flamed in some quarters, but docs endure and what's common knowledge or practice now may not be so this time next year.

  • Good overview as a lead, including examples and some various times when the product|module could|would be used.

  • Index thoroughly, including related keywords. If you use jargon others may not understand (now or in the future), they may not find what they need.

  • If the releases are modules or other tools, be very clear in the docs about the params into, and output of, each method or sub.

  • It's irksome to read the docs of modules that are written for a specialty field, and not really be able to quickly discern that. Be sure it's clear almost from the very beginning, what field or other specialty it applies to.

  • Rewrite...rewrite...rewrite

  • Get reviews, just like code reviews.

  • Version the docs as religiously as you version the product.

  • It's ok to have the docs have personality and some personalization. Pronouns are ok...

Have fun!


In reply to Re: Writing Good Documentation by tjh
in thread Writing Good Documentation by defyance

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 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 taking refuge in the Monastery: (3)
As of 2023-01-30 02:24 GMT
Find Nodes?
    Voting Booth?

    No recent polls found