<!DOCTYPE html><html><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><meta name="Author" content="Novell GroupWise WebAccess">
<style type="text/css">body { font-family:'DejaVu Sans Mono'; font-size:12px}</style>
</head>
<body style="font-family: Helvetica, Arial, sans-serif; font-size: 13px; ">Am 22.07.2014, 12:16 Uhr, schrieb Derek Hohls <dhohls@csir.co.za>:<br><br><blockquote style="margin: 0 0 0.80ex; border-left: #0000FF 2px solid; padding-left: 1ex">Is it not possible to require an absolutely minimum entry, at the correct place in the docs, for a new feature? For example, if a developer adds a new function X to a list of existing functions, already documented in section M.N, then at a minimum they need to add an entry saying "Function X (added 22/7/14): TBD". Anyone wanting to contribute to the docs can then (hopefully) easily search for undocumented features, both recent or ancient. It may even be possible to organise "doc sprints" based on this approach.<br></blockquote><div><div>+1 !</div><div><br></div></div><div><br></div><div><br></div><div><br></div><blockquote style="margin: 0 0 0.80ex; border-left: #0000FF 2px solid; padding-left: 1ex"><br>>>> Victor Olaya <volayaf@gmail.com> 07/22/14 12:02 PM >>><br><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"> <div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div>The solution is very simple: Require up to date, accurate documentation for all commits of new features. This is one for the PSC.</div> <div>After all, what's the point in having tons of features if no-one knows how to use them or what they do?</div> <div>Will it slow down new feature feature commit? Probably, but I figure that's a small price to pay for actually having documentation. And from that documentation, universal training materials can be developed much more easily.<br> </div></div></div></blockquote><div><br></div><div>-1 from me. Features are also documented by people using them, not just by the devs. We like to say that you can contribute to open source projects not just by coding, but if we do that, I don't think we are going to get many contributions from users, leaving the documentation to be written only by developers. </div> <div><br></div><div>I try to keep the Processing documentation up to date, but only documenting the interface itself and the framework, not the algorithms. That's the reason why a large part of algorithms in Processing are not documented. Fortunately, some users have contributed documentation, and they have added descriptions of several algorithms, but the have done that *after* using the (hitherto undocumented) algorithm and becoming familiar with it. No one is going to document something that he cannot use yet.</div> <div><br></div><div>Let's encourage developers to commit features when they are well documented, but let's also give some flexibility, since that's not always going to be possible.</div><br></div></div></div><font face="Verdana,Arial,Helvetica,Trebuchet MS" size="1"><p> </p></font><p><font face="Verdana,Arial,Helvetica,Trebuchet MS" size="1"> <br></font> </p><font face="Verdana,Arial,Helvetica,Trebuchet MS" size="1">
<br>--
<br>This message is subject to the CSIR's copyright terms and conditions, e-mail legal notice, and implemented Open Document Format (ODF) standard.
<br>The full disclaimer details can be found at <a href="http://www.csir.co.za/disclaimer.html">http://www.csir.co.za/disclaimer.html</a>.
<p>
<br>This message has been scanned for viruses and dangerous content by <a href="http://www.mailscanner.info/"><b>MailScanner</b></a>,
<br>and is believed to be clean.
</p></font><p><font face="Verdana,Arial,Helvetica,Trebuchet MS" size="1">
<br>Please consider the environment before printing this email.
</font>
</p></blockquote><br><br><br><div id="M2Signature"><div>-- </div><div>Bernd Vogelgesang<br>Siedlerstraße 2<br>91083 Baiersdorf/Igelsdorf<br>Tel: 09133-825374</div></div></body></html>