On Tue, Sep 8, 2009 at 6:53 PM, Mike Pumphrey<[email protected]> wrote: > Hi. I have to say that I'm -1 on a "pending" section for svn docs. When we > discussed the documentation framework last year, we decided that there should > be a place for finished docs, and a place for unfinished docs. We agreed > that Sphinx would be for the former and the Confluence wiki for the latter. > I think if we start throwing rough, unfinished docs into the User Manual, > then we will have defeated the purpose of trying to have polished > documentation. I would much prefer to attach pending docs to JIRA tasks. > What is the code equivalent to this discussion, a doc branch? If so, then if > we all agree that svn is the best place for these pages, then let's create a > _new_ Sphinx project for pending docs that won't be built with the Manuals.
+1 > That way, if nothing else, it won't be included with releases, +1 > won't be built and hosted live, -1 I need me as well as others to se what I am doing. Pending, while still pending, should be visibile. I hoping to see feedback from users (and clients) more than from other members of the committer list. Or are we writing docs for ourselves? > they won't be linked to, and people are way less likely to get > confused by looking at them. > > A la: > > User Manual (user/) > Developer Manual (developer/) > Documentation Guide (docguide/) > Pending Documentation (pending/) > +1, with the observation above. Ciao, Simone. > > Please let me know if I'm confused about what's being discussed here. > > Thanks, > Mike Pumphrey > OpenGeo - http://opengeo.org > > > Justin Deoliveira wrote: >> Simone Giannecchini wrote: >>> On Tue, Sep 8, 2009 at 5:56 PM, Justin Deoliveira<[email protected]> >>> wrote: >>>> <snip> >>>>> 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. >>>> Excellent points. >>>> >>>>> 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. >>>> Well branching would be the obvious answer with our current system. >>>> Although doing a full branch for working on docs is a bit of overkill. >>> I agree, overkill... >>> >>>> Another alternative could be to have a "pending" space. This could be >>>> more of a "scratch pad" type place where wiki type style writing can >>>> take place, at the same time having the docs integrated. Although >>>> pending docs would not be considered part of the finished product and >>>> stripped out of the doc artifacts when they are built. >>> This is exactly what I have in mind. Write the doc then ask for review >>> when you are ready. >> >> Cool. So I think the simplest way to do this would be have a pending >> directory under the top level directory. Underneath this directory we >> put pending docs. The structure could mirror the intended structure >> under the actual doc root. Examples for the recent mosaic tutorial: >> >> user/source/*pending*/tutorials/image_mosaic_plugin >> user/source/*pending*/styling/raster_symbolizer/ >> >> However this only works for new content. Patches to the existing docs >> obviously can't fall into this scheme. However those changes seem to be >> more targeted and have less content. So what about just sticking with >> the jira issue/patch/review approach given that we formalize the review >> process? >> >>>> A third answer is dsvc. >>> This is more a proposal than an answer :-) >>> >>> >>> I would say that 1 would work for the moment, 3 could be next step. >>> >>> >>> Ciao >>> Simone. >>>>> 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 >>>>>> >>>> -- >>>> 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 >> >> > > ------------------------------------------------------------------------------ > 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
