Hi All,
It is hard to figure out where in the conversation to interject but
Victors counter-suggestion appears appropriate to me.
Being involved in several open source projects, creating tutorials for
these and having in the past been involved with trying to contribute to
the main documentation for these packages it is obvious to me that
developers need to be involved in documentation.
Users rarely are able to decipher code and trying to figure out when and
how to use a particular feature can be quite daunting even for the most
experienced person.
Developers must provide at least basic information on what each new
feature does and what each feature (drop down box, radio button, etc) is
for. Without this users need to ferret through hundreds of emails and
forum posts, and pester the developers anyway. It is easier for devs to
provide a simple skeleton -- this does this, that does that, here is a
link, check out this bug etc. All this information is available at the
developers fingertips while they are working on the new feature anyway
-- it is just committing 30 minutes at the end to put some details down
on he page.
With this basic information, documenters are better equipped to present
the feature in context and explain how it should be used.
On 22/07/14 20:01, Victor Olaya wrote:
+1 to what Otto said. Very good point. Those creating training materials
should coordinate and help the core QGIS documentation (both the manual
and the training manual) improve.
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.
my 2 cents
Cheers
Víctor
--
Cheers Simon
Simon Cropper - Open Content Creator
Free and Open Source Software Workflow Guides
------------------------------------------------------------
Introduction http://www.fossworkflowguides.com
GIS Packages http://www.fossworkflowguides.com/gis
bash / Python http://www.fossworkflowguides.com/scripting
_______________________________________________
Qgis-user mailing list
Qgis-user@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/qgis-user
