[Qgis-developer] [Qgis-user] Stress about release plans

[Otto Dassau]

Hi Simon,

this sounds like a very good idea to me.

At the moment documenters look at the commit logs for a "[FEATURE]" comment
and add it to a wiki list. Then search through all mls, wikis and blogs, if
there is some howto available or at a least a short discussion or
description about that feature. If not we have to ask for help - all this
takes time...

If we have a simple skeleton about the feature automatically provided by
developers, we would be happy and it would be much easier to write a better
documentation.

Regards,
Otto

Am Wed, 23 Jul 2014 13:41:08 +1000
schrieb Simon Cropper <simoncropper at fossworkflowguides.com>:

> 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
> >
> 
> 


-- 
Geoinformatikbüro Dassau - http://www.gbd-consult.de
FOSSGIS consulting , training , support and analysis
Ackerstrasse 144c ,  D - 40233 Düsseldorf  , Germany
Tel: +49-(0)211-47468178 , Mobil: +49-(0)171-4687540

--
Community Advisor - QGIS Project Steering Committee