Ciao Justin, please read below... ------------------------------------------------------- Ing. Simone Giannecchini GeoSolutions S.A.S. Founder - Software Engineer Via Carignoni 51 55041 Camaiore (LU) Italy
phone: +39 0584983027 fax: +39 0584983027 mob: +39 333 8128928 http://www.geo-solutions.it http://geo-solutions.blogspot.com/ http://simboss.blogspot.com/ http://www.linkedin.com/in/simonegiannecchini ------------------------------------------------------- On Tue, Sep 8, 2009 at 5:11 PM, Justin Deoliveira<[email protected]> wrote: > I am seeing us fall into some bad habits with regard to user > documentation. Glancing over some recent doc commits it seems we are > falling back into "wiki-like" informal language and slang. > > Remember that the accepted style guide reminds to avoid slang and > "colorful" language. But also to be direct. > > http://docs.geoserver.org/trunk/en/docguide/style.html > > I of course realize that not everyone is a native english speaker. Which > I think is another reason to have a maintainer for docs in each language. > > I also think that it will be useful to again point that the sphinx docs > are meant for "production" or "finished" docs. (Or at least that was my > understanding). For stuff that is meant to be quickly mocked up I think > the wiki is still appropriate. I know this results in work in porting > docs from the wiki to sphinx when they are ready. But I think it is more > important to preserve cleanliness in the docs, and avoid the state that > the confluence user guide is in (a mess). I don't think that this way of producing docs would work at least not for us. 1> Working with the wiki is a real pain 2> We often use more than on computer for our work, hence we need to make use of svn 3> Documentation time is expensive, we cannot afford writing on the wiki and maintaining patches. I don't wish to put our private svn in the loop. Therefore, simple suggestion, we should think about a scheme where the docs get committed to svn right away and then moved into "production-ready" documentation once a formal review has been made (I would add between N days). This would make everyone happy I guess. Ciao, Simone. > > 2c, > > -Justin > > Mike Pumphrey wrote: >> I don't think the idea was abandoned, but I also don't think it was adopted >> as dogma. >> >> Is there a section I should take a look at and/or go in with my vacuum >> cleaner? :) Just let me know... >> >> Thanks, >> Mike Pumphrey >> OpenGeo - http://opengeo.org >> >> >> Justin Deoliveira wrote: >>> Hi all, >>> >>> Apologies if I missed something while I was away but I thought before we >>> more or less agreed that we would adopt Mike as the user guide doc >>> maintainer and that non-trivial changes should go through him via patches? >>> >>> Did we abandon that as a bad idea? >>> >>> -Justin >>> >> >> ------------------------------------------------------------------------------ >> Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day >> trial. Simplify your report design, integration and deployment - and focus on >> what you do best, core application coding. Discover what's new with >> Crystal Reports now. http://p.sf.net/sfu/bobj-july >> _______________________________________________ >> Geoserver-devel mailing list >> [email protected] >> https://lists.sourceforge.net/lists/listinfo/geoserver-devel > > > -- > Justin Deoliveira > OpenGeo - http://opengeo.org > Enterprise support for open source geospatial. > > ------------------------------------------------------------------------------ > Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day > trial. Simplify your report design, integration and deployment - and focus on > what you do best, core application coding. Discover what's new with > Crystal Reports now. http://p.sf.net/sfu/bobj-july > _______________________________________________ > Geoserver-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/geoserver-devel > ------------------------------------------------------------------------------ Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day trial. Simplify your report design, integration and deployment - and focus on what you do best, core application coding. Discover what's new with Crystal Reports now. http://p.sf.net/sfu/bobj-july _______________________________________________ Geoserver-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/geoserver-devel
