These are all valid points and are generally good to follow. However, one should also look down at how much time has been alotted to documenting your product. In my experience, I was never able to apply all of the above mentioned points completely due to time constraints imposed by various factors (management being one of them ;). Although, documentation is a very important piece, in practice there's not always enough time to finish it off.
Thus, a few suggestions as to how you might save time all the while produce sufficient documentation.
- Write your documentation as you move through your project. Project managers sometimes overlook the need for allowing extra time to add documentation to a working code. Most often, they are reluctant to do so when you are all done and the product seems to work just fine (especially in the Web environment, the project is simply closed with too little documentation). However, if you were to ask for a little bit more time during the coding phase (write it off on various factors if you don't really want to disclose the detailed facts), they'll normally give in and thereby provide you with ample room to fit adequate documentation.
- Write your documentation to look perfect (as much as you possible can) the first time. I know, I know! It is not always possible and I'm nuts for suggesting it, but what I'm saying is at least make it a 'point' to drive at. This will reduce the time you'll have to spend to hack at poorly written/organized documentation.
- This leads to the next point... Organize your documentation, always! ;). A good documentation outline will normally lead to a well written documentation with minimal time spent writing it.
_____________________
# Under Construction
-
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.
|
