Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
If you happen to be hit by a bus, chances are that no matter how clearly and completely you write the text of your documentation, an emergency situation will come up before your (hopefully more bus-resistant replacement) will be able to read it all.

That isn't to say that you shouldn't bother writing it... By all means, you should.

I'm a strong proponent of application flow diagrams. In a pinch, it's much easier to see which other things the little picture of 'sqldb19' has lines running to, than to scan through pages of text, hoping that you don't miss a reference to 'sqldb10-20.'

Note that sqldb19 doesn't need to be a seperate server for this to work. I apply this type of graphical overview to things like cron jobs that summarize data, to be able to know which reports will be wrong if suddenly the cron jobs all stop. It's easy to trace the lines to the sql server, then to the web servers that query it.

Eh, I tend to be pretty visual, so maybe this is just me...

In reply to Re: How to write documentation? by Hutta
in thread How to write documentation? by ajt

Title:
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?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others exploiting the Monastery: (2)
As of 2021-12-05 18:19 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    R or B?



    Results (31 votes). Check out past polls.

    Notices?