<HTML><BODY style="word-wrap: break-word; -khtml-nbsp-mode: space; -khtml-line-break: after-white-space; "><BR><DIV><DIV>On Aug 13, 2005, at 12:41 PM, Roderick A. Anderson wrote:</DIV><BLOCKQUOTE type="cite"><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">how</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">to document _invisible_ scripts.<SPAN class="Apple-converted-space"> </SPAN>Those that only a coder will look but</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">aren't really modules.<SPAN class="Apple-converted-space"> </SPAN>Maybe it's my naivety but I don't see the "normal"</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">pod documentation doing much good in these since they should almost never</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">be run from a command line.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">What I'm interested in is how those of you that write web apps document</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">your code.</DIV></BLOCKQUOTE></DIV><BR><DIV><FONT class="Apple-style-span" color="#0000DD">There are three consumers of code you write:</FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD">1. You, the author</FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD">2</FONT><FONT class="Apple-style-span" color="#0000DD">. Other developers and code maintainers</FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD">3. Users</FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD"><BR class="khtml-block-placeholder"></FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD">I write different comments for all three. Let's consider your example of a web app.</FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD"><BR class="khtml-block-placeholder"></FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD">For other developers and people who will follow in my footsteps, either maintaining code or adding features, I write POD documentation. General methodology is explained; how all the larger pieces fit together. How to use these pieces. Examples. Where to go for more information.</FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD"><BR class="khtml-block-placeholder"></FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD">For myself, I write comments. Why did I write a method one particular way. Why did I use one strategy instead of another. Anything strange; anything klugy, anything that might make me scratch my head after a year should be commented.</FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD"><BR class="khtml-block-placeholder"></FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD">Users get webpages. If they're already in a browser, why make them go elsewhere?</FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD"><BR class="khtml-block-placeholder"></FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD">As you can see, POD is still extremely important. The only time I don't feel obliged to write POD is for something like a CGI::Application program, a program that has only two or three lines of code, where the modules used are already well-documented.</FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD"><BR class="khtml-block-placeholder"></FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD">Hope this helps,</FONT></DIV><DIV><FONT class="Apple-style-span" color="#0000DD">Joshua</FONT></DIV></BODY></HTML>