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.
>>> Victor Olaya <[email protected]> 07/22/14 12:02 PM >>> The solution is very simple: Require up to date, accurate documentation for all commits of new features. This is one for the PSC. After all, what's the point in having tons of features if no-one knows how to use them or what they do? 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. -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. 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. 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. -- This message is subject to the CSIR's copyright terms and conditions, e-mail legal notice, and implemented Open Document Format (ODF) standard. The full disclaimer details can be found at http://www.csir.co.za/disclaimer.html. This message has been scanned for viruses and dangerous content by MailScanner, and is believed to be clean. Please consider the environment before printing this email.
_______________________________________________ Qgis-user mailing list [email protected] http://lists.osgeo.org/mailman/listinfo/qgis-user
