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 <simoncrop...@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-developer mailing list Qgis-developer@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/qgis-developer