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

[Otto Dassau]

Hi Nathan,

thanks for the offer, but this is not the problem. After feature freeze we
currently do a git log --since=<date> --grep='FEATURE'", that's ok. And Tims
changelog is also very helpful and often already fine as a beginning.

The result is in the wiki: http://hub.qgis.org/wiki/17/ManualTasks

But this covers not all changes we need to document nor does it usually
describe the usage. We still we have to search the web, so it would be great
to have a simple skeleton with a short description of all functionality of a
feature from the developers, if that is possible. 

Maybe we can offer 2 ways. If developers write about features in their blog
and describe how it works, as you do, you could just add the link
somewhere where documenters can look it up. For others a simple
documentation skeleton could be used as a standard.

Whatever we finally use, it would be good to improve the current procedure.

Regards
Otto  

Am Wed, 23 Jul 2014 17:43:51 +1000
schrieb Nathan Woodrow <madmanwoo at gmail.com>:

> We could make a script to just pull out everything with [FEATURE] in the
> commit between a date range if that will help.  Maybe we could create stubs
> in Tims changelog system using something like this.
> 
> - Nathan
> 
> 
> On Wed, Jul 23, 2014 at 5:28 PM, Otto Dassau <dassau at gbd-consult.de> wrote:
> 
> > 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
> > _______________________________________________
> > Qgis-user mailing list
> > Qgis-user at lists.osgeo.org
> > http://lists.osgeo.org/mailman/listinfo/qgis-user
> >


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