Am 22.07.2014, 12:16 Uhr, schrieb Derek Hohls <dho...@csir.co.za>:
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.
+1 !
Victor Olaya <vola...@gmail.com> 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.
--
Bernd Vogelgesang
Siedlerstraße 2
91083 Baiersdorf/Igelsdorf
Tel: 09133-825374
_______________________________________________
Qgis-user mailing list
Qgis-user@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/qgis-user
