[Geoserver-devel] user guide doc commits

Justin_Deoliveira · September 8, 2009, 2:59pm

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

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Michael_Melvin · September 8, 2009, 3:01pm

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

Justin_Deoliveira · September 8, 2009, 3:04pm

Well following the commit list I saw a wack of commits to the user guide from Simone, which is why i asked.

Modified Paths

* trunk/doc/en/user/source/services/wms/index.rst

Added Paths

     * trunk/doc/en/user/source/services/wms/reference/
     * trunk/doc/en/user/source/services/wms/reference/describe_layer/
     * trunk/doc/en/user/source/services/wms/reference/describe_layer/capabilities.rst
     * trunk/doc/en/user/source/services/wms/reference/get_capabilities/
     * trunk/doc/en/user/source/services/wms/reference/get_capabilities/capabilities.rst
     * trunk/doc/en/user/source/services/wms/reference/get_feature_info/
     * trunk/doc/en/user/source/services/wms/reference/get_feature_info/featureinfo.rst
     * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/
     * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/
     * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend1.png
     * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend2.png
     * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend3.png
     * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend4.png
     * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend5.png
     * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/samplelegend.png
     * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/legendgraphic.rst
     * trunk/doc/en/user/source/services/wms/reference/get_map/
     * trunk/doc/en/user/source/services/wms/reference/get_map/map.rst
     * trunk/doc/en/user/source/services/wms/reference/index.rst

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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Andrea_Aime3 · September 8, 2009, 3:08pm

Justin Deoliveira ha scritto:

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?

For minor changes and 1-1 copies from the wiki I committed right
away and asked Mike to review in the relevant jiras.
I remember we talked about asking for reviews, not that the rule was
to have a review before the commit.
Btw, I've tried pre-commit reviews too and I had some
patches linger on the jira for weeks... 3 weeks and counting
for this one for example: http://jira.codehaus.org/browse/GEOS-3339.
So for smaller stuff I've started to just commit and ask for a post
review.

Cheers
Andrea

--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

Simone_Giannecchini3 · September 8, 2009, 3:11pm

.... and more should be on its way

I am not against this sort of babysitting, especially becausue the
longer the document is the worse my english gets towards the end.
Nevertheless I have to admit that lately I feel like I have to ask
permission to even do my own work. I hope this is just an impression.

Simone.
-------------------------------------------------------
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:04 PM, Justin Deoliveira<jdeolive@anonymised.com> wrote:

Well following the commit list I saw a wack of commits to the user guide
from Simone, which is why i asked.

Modified Paths
\* trunk/doc/en/user/source/services/wms/index\.rst
Added Paths
\* trunk/doc/en/user/source/services/wms/reference/
\* trunk/doc/en/user/source/services/wms/reference/describe\_layer/
\*
trunk/doc/en/user/source/services/wms/reference/describe_layer/capabilities.rst
* trunk/doc/en/user/source/services/wms/reference/get_capabilities/
*
trunk/doc/en/user/source/services/wms/reference/get_capabilities/capabilities.rst
* trunk/doc/en/user/source/services/wms/reference/get_feature_info/
*
trunk/doc/en/user/source/services/wms/reference/get_feature_info/featureinfo.rst
* trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend1.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend2.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend3.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend4.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend5.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/samplelegend.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/legendgraphic.rst
* trunk/doc/en/user/source/services/wms/reference/get_map/
* trunk/doc/en/user/source/services/wms/reference/get_map/map.rst
* trunk/doc/en/user/source/services/wms/reference/index.rst

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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

Justin_Deoliveira · September 8, 2009, 3:11pm

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

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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Justin_Deoliveira · September 8, 2009, 3:13pm

Andrea Aime wrote:

Justin Deoliveira ha scritto:

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?

For minor changes and 1-1 copies from the wiki I committed right
away and asked Mike to review in the relevant jiras.

Hmmm... minor changes i would agree require no review, but straight copies from the wiki i would disagree. The reason being that part of the port from the wiki to sphinx has been quality control on the docs.

I remember we talked about asking for reviews, not that the rule was
to have a review before the commit.
Btw, I've tried pre-commit reviews too and I had some
patches linger on the jira for weeks... 3 weeks and counting
for this one for example: http://jira.codehaus.org/browse/GEOS-3339.
So for smaller stuff I've started to just commit and ask for a post
review.

Fair enough. I know that not everyone watches jira as closely as some. We should ask mike if he is actually getting notification of these patches?

Cheers
Andrea

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Justin_Deoliveira · September 8, 2009, 3:16pm

Simone Giannecchini wrote:

.... and more should be on its way

I am not against this sort of babysitting, especially becausue the
longer the document is the worse my english gets towards the end.
Nevertheless I have to admit that lately I feel like I have to ask
permission to even do my own work. I hope this is just an impression.

I think your impression is correct, although misphrased. No one wants to be the overseer or have the right to give the OK of what gets done. Just the right to do code review which results in much higher quality work.

If this is becoming a bit much I understand, but it means that committers must be more careful about what they are commiting. To be blunt the docs you recently commit blatantly disregard the agreed doc guidelines.

Simone.
-------------------------------------------------------
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:04 PM, Justin Deoliveira<jdeolive@anonymised.com> wrote:

Well following the commit list I saw a wack of commits to the user guide
from Simone, which is why i asked.

Modified Paths

    * trunk/doc/en/user/source/services/wms/index.rst

Added Paths

    * trunk/doc/en/user/source/services/wms/reference/
    * trunk/doc/en/user/source/services/wms/reference/describe_layer/
    *
trunk/doc/en/user/source/services/wms/reference/describe_layer/capabilities.rst
    * trunk/doc/en/user/source/services/wms/reference/get_capabilities/
    *
trunk/doc/en/user/source/services/wms/reference/get_capabilities/capabilities.rst
    * trunk/doc/en/user/source/services/wms/reference/get_feature_info/
    *
trunk/doc/en/user/source/services/wms/reference/get_feature_info/featureinfo.rst
    * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend1.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend2.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend3.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend4.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend5.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/samplelegend.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/legendgraphic.rst
    * trunk/doc/en/user/source/services/wms/reference/get_map/
    * trunk/doc/en/user/source/services/wms/reference/get_map/map.rst
    * trunk/doc/en/user/source/services/wms/reference/index.rst

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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Andrea_Aime3 · September 8, 2009, 3:24pm

Justin Deoliveira ha scritto:

Simone Giannecchini wrote:

.... and more should be on its way

I am not against this sort of babysitting, especially becausue the
longer the document is the worse my english gets towards the end.
Nevertheless I have to admit that lately I feel like I have to ask
permission to even do my own work. I hope this is just an impression.

I think your impression is correct, although misphrased. No one wants to be the overseer or have the right to give the OK of what gets done. Just the right to do code review which results in much higher quality work.

Justin,
I know you're big on reviews and I agree they do make for higher
quality.

Some projects, like OL, have established rules where each commit
has to be reviewed by at least two other committers, or stuff like
that.

I don't disagree going down that path, but imho that requires a GSIP
that is voted unanimously. It also requires a change of mind in
how promptly reviews are done (having someone stuck for weeks
or more is not good), maybe establishing a window for reviews,
and have the patch land in case of no review (just like we do
for IP in GeoTools, to avoid someone get stuck due to lack of
interest).

Given that GoeServer lacks formal module ownership we should also
either establish some or decide that any committer that feels
entitled to review can.

Anyways, despite the form, such governance rules should be
described and voted in a GSIP imho

Cheers
Andrea

--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

Justin_Deoliveira · September 8, 2009, 3:30pm

Good points Andrea. I agree, up until this point there has been no formal rules about review, yet certain practices and conventions have been evolving. I will throw up what I think the current practices have become and throw them into a GSIP when I get a chance.

Andrea Aime wrote:

Justin Deoliveira ha scritto:

Simone Giannecchini wrote:

.... and more should be on its way

I am not against this sort of babysitting, especially becausue the
longer the document is the worse my english gets towards the end.
Nevertheless I have to admit that lately I feel like I have to ask
permission to even do my own work. I hope this is just an impression.

I think your impression is correct, although misphrased. No one wants to be the overseer or have the right to give the OK of what gets done. Just the right to do code review which results in much higher quality work.

Justin,
I know you're big on reviews and I agree they do make for higher
quality.

Some projects, like OL, have established rules where each commit
has to be reviewed by at least two other committers, or stuff like
that.

I don't disagree going down that path, but imho that requires a GSIP
that is voted unanimously. It also requires a change of mind in
how promptly reviews are done (having someone stuck for weeks
or more is not good), maybe establishing a window for reviews,
and have the patch land in case of no review (just like we do
for IP in GeoTools, to avoid someone get stuck due to lack of
interest).

Given that GoeServer lacks formal module ownership we should also
either establish some or decide that any committer that feels
entitled to review can.

Anyways, despite the form, such governance rules should be
described and voted in a GSIP imho

Cheers
Andrea

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Simone_Giannecchini3 · September 8, 2009, 3:36pm

On Tue, Sep 8, 2009 at 5:16 PM, Justin Deoliveira<jdeolive@anonymised.com> wrote:

Simone Giannecchini wrote:

.... and more should be on its way

I am not against this sort of babysitting, especially becausue the
longer the document is the worse my english gets towards the end.
Nevertheless I have to admit that lately I feel like I have to ask
permission to even do my own work. I hope this is just an impression.

I think your impression is correct, although misphrased.

Misphrased or not, if my impression is correct, well then that might
be a problem.
In this specific case, I don't see a particular problem in submitting
patches, but I won't ensure that I am going to do that all the time,
even because I might forget it.

About the docs I committed, you are right, but as you noticed we are
still working on them, updpating them and reviewing them, so I am
actually happy that you looked at them, I was thinking about asking
Mike to review them when they were ready but I was a bit reluctant
about doing that. Now I know for usure that I can do that.
Anywyay, guidelines != rules, I am not against them but yeah, I don't
like to ask permission to scratch my head.

Ciao,
Simone.

No one wants to
be the overseer or have the right to give the OK of what gets done. Just
the right to do code review which results in much higher quality work.

If this is becoming a bit much I understand, but it means that
committers must be more careful about what they are commiting. To be
blunt the docs you recently commit blatantly disregard the agreed doc
guidelines.
Simone.
-------------------------------------------------------
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:04 PM, Justin Deoliveira<jdeolive@anonymised.com> wrote:
Well following the commit list I saw a wack of commits to the user guide
from Simone, which is why i asked.

Modified Paths
\* trunk/doc/en/user/source/services/wms/index\.rst
Added Paths
\* trunk/doc/en/user/source/services/wms/reference/
\* trunk/doc/en/user/source/services/wms/reference/describe\_layer/
\*
trunk/doc/en/user/source/services/wms/reference/describe_layer/capabilities.rst
* trunk/doc/en/user/source/services/wms/reference/get_capabilities/
*
trunk/doc/en/user/source/services/wms/reference/get_capabilities/capabilities.rst
* trunk/doc/en/user/source/services/wms/reference/get_feature_info/
*
trunk/doc/en/user/source/services/wms/reference/get_feature_info/featureinfo.rst
* trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend1.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend2.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend3.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend4.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend5.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/samplelegend.png
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/legendgraphic.rst
* trunk/doc/en/user/source/services/wms/reference/get_map/
* trunk/doc/en/user/source/services/wms/reference/get_map/map.rst
* trunk/doc/en/user/source/services/wms/reference/index.rst

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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

Justin_Deoliveira · September 8, 2009, 3:41pm

Simone Giannecchini wrote:

On Tue, Sep 8, 2009 at 5:16 PM, Justin Deoliveira<jdeolive@anonymised.com> wrote:

Simone Giannecchini wrote:

.... and more should be on its way

I am not against this sort of babysitting, especially becausue the
longer the document is the worse my english gets towards the end.
Nevertheless I have to admit that lately I feel like I have to ask
permission to even do my own work. I hope this is just an impression.

I think your impression is correct, although misphrased.

Misphrased or not, if my impression is correct, well then that might
be a problem.
In this specific case, I don't see a particular problem in submitting
patches, but I won't ensure that I am going to do that all the time,
even because I might forget it.

About the docs I committed, you are right, but as you noticed we are
still working on them, updpating them and reviewing them, so I am
actually happy that you looked at them, I was thinking about asking
Mike to review them when they were ready but I was a bit reluctant
about doing that.

Well I would suggest using the wiki as a "scatch pad" if this is the case. But perhaps not everyone shares my desire to keep the sphinx docs nice and clean, although I had thought this was informally agreed upon at some point.

Now I know for usure that I can do that.

Anywyay, guidelines != rules, I am not against them but yeah, I don't
like to ask permission to scratch my head.

I don't really appreciate the overstatement, but I get the message. And I object to the argument of disregarding a guideline because it is not considered a rule. Unless there is a good reason for not following a guideline (and i see none here) it should be followed the same as a "rule" imho.

Ciao,
Simone.

No one wants to
be the overseer or have the right to give the OK of what gets done. Just
the right to do code review which results in much higher quality work.

If this is becoming a bit much I understand, but it means that
committers must be more careful about what they are commiting. To be
blunt the docs you recently commit blatantly disregard the agreed doc
guidelines.

Simone.
-------------------------------------------------------
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:04 PM, Justin Deoliveira<jdeolive@anonymised.com> wrote:

Well following the commit list I saw a wack of commits to the user guide
from Simone, which is why i asked.

Modified Paths

    * trunk/doc/en/user/source/services/wms/index.rst

Added Paths

    * trunk/doc/en/user/source/services/wms/reference/
    * trunk/doc/en/user/source/services/wms/reference/describe_layer/
    *
trunk/doc/en/user/source/services/wms/reference/describe_layer/capabilities.rst
    * trunk/doc/en/user/source/services/wms/reference/get_capabilities/
    *
trunk/doc/en/user/source/services/wms/reference/get_capabilities/capabilities.rst
    * trunk/doc/en/user/source/services/wms/reference/get_feature_info/
    *
trunk/doc/en/user/source/services/wms/reference/get_feature_info/featureinfo.rst
    * trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend1.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend2.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend3.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend4.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend5.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/samplelegend.png
    *
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/legendgraphic.rst
    * trunk/doc/en/user/source/services/wms/reference/get_map/
    * trunk/doc/en/user/source/services/wms/reference/get_map/map.rst
    * trunk/doc/en/user/source/services/wms/reference/index.rst

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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Simone_Giannecchini3 · September 8, 2009, 3:45pm

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<jdeolive@anonymised.com> 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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

Simone_Giannecchini3 · September 8, 2009, 3:47pm

On Tue, Sep 8, 2009 at 5:41 PM, Justin Deoliveira<jdeolive@anonymised.com> wrote:

Simone Giannecchini wrote:

On Tue, Sep 8, 2009 at 5:16 PM, Justin Deoliveira<jdeolive@anonymised.com>
wrote:

Simone Giannecchini wrote:

.... and more should be on its way

I am not against this sort of babysitting, especially becausue the
longer the document is the worse my english gets towards the end.
Nevertheless I have to admit that lately I feel like I have to ask
permission to even do my own work. I hope this is just an impression.

I think your impression is correct, although misphrased.

Misphrased or not, if my impression is correct, well then that might
be a problem.
In this specific case, I don't see a particular problem in submitting
patches, but I won't ensure that I am going to do that all the time,
even because I might forget it.

About the docs I committed, you are right, but as you noticed we are
still working on them, updpating them and reviewing them, so I am
actually happy that you looked at them, I was thinking about asking
Mike to review them when they were ready but I was a bit reluctant
about doing that.

Well I would suggest using the wiki as a "scatch pad" if this is the case.
But perhaps not everyone shares my desire to keep the sphinx docs nice and
clean, although I had thought this was informally agreed upon at some point.

Now I know for usure that I can do that.

Anywyay, guidelines != rules, I am not against them but yeah, I don't
like to ask permission to scratch my head.

I don't really appreciate the overstatement, but I get the message. And I
object to the argument of disregarding a guideline because it is not
considered a rule. Unless there is a good reason for not following a
guideline (and i see none here) it should be followed the same as a "rule"
imho.

Ciao Justin, don't get me wrong, I am not trying to start a flame.
Btw, see my other email.

Simone.

Ciao,
Simone.

No one wants to
be the overseer or have the right to give the OK of what gets done. Just
the right to do code review which results in much higher quality work.

If this is becoming a bit much I understand, but it means that
committers must be more careful about what they are commiting. To be
blunt the docs you recently commit blatantly disregard the agreed doc
guidelines.

Simone.
-------------------------------------------------------
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:04 PM, Justin Deoliveira<jdeolive@anonymised.com>
wrote:

Well following the commit list I saw a wack of commits to the user
guide
from Simone, which is why i asked.

Modified Paths

* trunk/doc/en/user/source/services/wms/index.rst

Added Paths

* trunk/doc/en/user/source/services/wms/reference/
* trunk/doc/en/user/source/services/wms/reference/describe_layer/
*

trunk/doc/en/user/source/services/wms/reference/describe_layer/capabilities.rst
* trunk/doc/en/user/source/services/wms/reference/get_capabilities/
*

trunk/doc/en/user/source/services/wms/reference/get_capabilities/capabilities.rst
* trunk/doc/en/user/source/services/wms/reference/get_feature_info/
*

trunk/doc/en/user/source/services/wms/reference/get_feature_info/featureinfo.rst
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/
*
trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/
*

trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend1.png
*

trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend2.png
*

trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend3.png
*

trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend4.png
*

trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/rasterlegend5.png
*

trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/img/samplelegend.png
*

trunk/doc/en/user/source/services/wms/reference/get_legend_graphic/legendgraphic.rst
* trunk/doc/en/user/source/services/wms/reference/get_map/
* trunk/doc/en/user/source/services/wms/reference/get_map/map.rst
* trunk/doc/en/user/source/services/wms/reference/index.rst

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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Justin_Deoliveira · September 8, 2009, 3:56pm

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

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.

A third answer is dsvc.

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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Simone_Giannecchini3 · September 8, 2009, 4:00pm

On Tue, Sep 8, 2009 at 5:56 PM, Justin Deoliveira<jdeolive@anonymised.com> 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.

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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

Simone_Giannecchini3 · September 8, 2009, 4:07pm

On Tue, Sep 8, 2009 at 6:00 PM, Simone
Giannecchini<simone.giannecchini@anonymised.com> wrote:

On Tue, Sep 8, 2009 at 5:56 PM, Justin Deoliveira<jdeolive@anonymised.com> 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.

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.

Ops, correcting myself, *2* would work, 3 could be next step.

Simone.

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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

Justin_Deoliveira · September 8, 2009, 4:15pm

Simone Giannecchini wrote:

On Tue, Sep 8, 2009 at 5:56 PM, Justin Deoliveira<jdeolive@anonymised.com> 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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

Michael_Melvin · September 8, 2009, 4:53pm

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. That way, if nothing else, it won't be included with releases, won't be built and hosted live, 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/)

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<jdeolive@anonymised.com> 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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

Simone_Giannecchini3 · September 8, 2009, 5:32pm

On Tue, Sep 8, 2009 at 6:53 PM, Mike Pumphrey<mike@anonymised.com> 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<jdeolive@anonymised.com> 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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel