[Qgis-user] Stress about release plans

[Simon Cropper]

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