Hi all. This is just a reminder to anyone who is committing changes/updates/additions to the GeoServer documentation to please build the docs and verify that there are no errors, just as you would not commit any code before ensuring that it compiles correctly. I'm happy that people are adding to the docs, but making sure that the project has no warnings/syntax errors ensures a happy place that's more conducive for everyone to contribute. If you have work you'd like to put up for review, you can always file a JIRA and even assign it to me, and I'll do my best to review it for style/legibility, if not actual correctness.
Thanks all, and sorry for the nag. Although, while I'm at it, when's the last time you cleaned your room? 
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
Thanks Mike.
I think it would actually be good to have a pseudo module maintainer for docs. The primary reason being that I think the best way to keep documentation consistent and flowing is to have a single "editor".
I am not sure how others would feel but I would be cool with submitting documentation changes via patch for review if you were cool with it Mike. Interested in how the other devs feel.
-Justin
Mike Pumphrey wrote:
Hi all. This is just a reminder to anyone who is committing changes/updates/additions to the GeoServer documentation to please build the docs and verify that there are no errors, just as you would not commit any code before ensuring that it compiles correctly. I'm happy that people are adding to the docs, but making sure that the project has no warnings/syntax errors ensures a happy place that's more conducive for everyone to contribute. If you have work you'd like to put up for review, you can always file a JIRA and even assign it to me, and I'll do my best to review it for style/legibility, if not actual correctness.
Thanks all, and sorry for the nag. Although, while I'm at it, when's the last time you cleaned your room?
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
------------------------------------------------------------------------------
_______________________________________________
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 ha scritto:
Thanks Mike.
I think it would actually be good to have a pseudo module maintainer for docs. The primary reason being that I think the best way to keep documentation consistent and flowing is to have a single "editor".
I am not sure how others would feel but I would be cool with submitting documentation changes via patch for review if you were cool with it Mike. Interested in how the other devs feel.
I think it would be good, review increase quality.
But I'm troubled with the concept of a single person deciding of the
destiny of any part of the system. Having a single person managing
docs will ensure the document is consistent and flows, but I want to
make sure the same person cannot turn into a despot, but be a manager
instead.
One way to ensure that is that the rules for writing docs are clearly
stated somewhere (the doc guide already has some) and that new
requirements for writing docs are discussed as a community and then
merged into the guide: this way the maintainer manages the documentation
merge but cannot turn into a ruler of the module, since he does not make
the rules (much like the separation between law making and law
enforcement in reality).
Cheers
Andrea
--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.
I was suggesting as much, actually. It doesn't have to be me, of course, but I will gladly volunteer. I don't claim to have any great wisdom when it comes to technical writing, so if someone steps up who pulls rank on me, I'll gladly defer.
One specific aside that I thought of after sending my previous message:
Q: What if I want to create an internal reference, but I haven't actually written the referenced section?
A1: Create the reference, then create a blank reference section (i.e. just the section header, with no content), so that the link verifies and future writers know what the reference is supposed to go to.
A2: Don't create a reference link, and add one in later when the section is added.
(The idea is to prevent broken links)
I'll put this in the docguide too, but just thought I'd throw it out here, as I've caught a bunch of these Links To Nowhere.
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
Justin Deoliveira wrote:
Thanks Mike.
I think it would actually be good to have a pseudo module maintainer for docs. The primary reason being that I think the best way to keep documentation consistent and flowing is to have a single "editor".
I am not sure how others would feel but I would be cool with submitting documentation changes via patch for review if you were cool with it Mike. Interested in how the other devs feel.
-Justin
Mike Pumphrey wrote:
Hi all. This is just a reminder to anyone who is committing changes/updates/additions to the GeoServer documentation to please build the docs and verify that there are no errors, just as you would not commit any code before ensuring that it compiles correctly. I'm happy that people are adding to the docs, but making sure that the project has no warnings/syntax errors ensures a happy place that's more conducive for everyone to contribute. If you have work you'd like to put up for review, you can always file a JIRA and even assign it to me, and I'll do my best to review it for style/legibility, if not actual correctness.
Thanks all, and sorry for the nag. Although, while I'm at it, when's the last time you cleaned your room?
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
I don't think I was trying to suggest that all docs _have_ to go through me, only that I am making myself available should people wish to have someone review.
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
Andrea Aime wrote:
Justin Deoliveira ha scritto:
Thanks Mike.
I think it would actually be good to have a pseudo module maintainer for docs. The primary reason being that I think the best way to keep documentation consistent and flowing is to have a single "editor".
I am not sure how others would feel but I would be cool with submitting documentation changes via patch for review if you were cool with it Mike. Interested in how the other devs feel.
I think it would be good, review increase quality.
But I'm troubled with the concept of a single person deciding of the
destiny of any part of the system. Having a single person managing
docs will ensure the document is consistent and flows, but I want to
make sure the same person cannot turn into a despot, but be a manager
instead.
One way to ensure that is that the rules for writing docs are clearly
stated somewhere (the doc guide already has some) and that new
requirements for writing docs are discussed as a community and then
merged into the guide: this way the maintainer manages the documentation
merge but cannot turn into a ruler of the module, since he does not make
the rules (much like the separation between law making and law
enforcement in reality).
Cheers
Andrea
But I'm troubled with the concept of a single person deciding of the
destiny of any part of the system. Having a single person managing
docs will ensure the document is consistent and flows, but I want to
make sure the same person cannot turn into a despot, but be a manager
instead.
One way to ensure that is that the rules for writing docs are clearly
stated somewhere (the doc guide already has some) and that new
requirements for writing docs are discussed as a community and then
merged into the guide: this way the maintainer manages the documentation
merge but cannot turn into a ruler of the module, since he does not make
the rules (much like the separation between law making and law
enforcement in reality).
Agreed on all fronts. I don't think anyone wants to place the docs or any other part of the system under lock and key subject to one persons whims. As with any contribution there should be a good and documented reason for asking someone to modify or rework something.
Coming up with a complete docguide is no easy task though. In my opinion it will need to be something that evolves over time. I would suggest that if Mike were to come the maintainer or editor of the docs that we have a well defined process for him to gradually update the doc guidelines (with the community of course) as contributions come in and more docs get written.
Cheers
Andrea
--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.
Good question. I would say perhaps say A2, but ammeded to make use of the sphinx 'todo' extension, used to annotate a doc with a list of todo items. Same deal as with confluence.
Mike Pumphrey wrote:
I was suggesting as much, actually. It doesn't have to be me, of course, but I will gladly volunteer. I don't claim to have any great wisdom when it comes to technical writing, so if someone steps up who pulls rank on me, I'll gladly defer.
One specific aside that I thought of after sending my previous message:
Q: What if I want to create an internal reference, but I haven't actually written the referenced section?
A1: Create the reference, then create a blank reference section (i.e. just the section header, with no content), so that the link verifies and future writers know what the reference is supposed to go to.
A2: Don't create a reference link, and add one in later when the section is added.
(The idea is to prevent broken links)
I'll put this in the docguide too, but just thought I'd throw it out here, as I've caught a bunch of these Links To Nowhere.
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
Justin Deoliveira wrote:
Thanks Mike.
I think it would actually be good to have a pseudo module maintainer for docs. The primary reason being that I think the best way to keep documentation consistent and flowing is to have a single "editor".
I am not sure how others would feel but I would be cool with submitting documentation changes via patch for review if you were cool with it Mike. Interested in how the other devs feel.
-Justin
Mike Pumphrey wrote:
Hi all. This is just a reminder to anyone who is committing changes/updates/additions to the GeoServer documentation to please build the docs and verify that there are no errors, just as you would not commit any code before ensuring that it compiles correctly. I'm happy that people are adding to the docs, but making sure that the project has no warnings/syntax errors ensures a happy place that's more conducive for everyone to contribute. If you have work you'd like to put up for review, you can always file a JIRA and even assign it to me, and I'll do my best to review it for style/legibility, if not actual correctness.
Thanks all, and sorry for the nag. Although, while I'm at it, when's the last time you cleaned your room?
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
------------------------------------------------------------------------------
_______________________________________________
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 ha scritto:
> Agreed on all fronts. I don't think anyone wants to place the docs or
any other part of the system under lock and key subject to one persons whims. As with any contribution there should be a good and documented reason for asking someone to modify or rework something.
Coming up with a complete docguide is no easy task though. In my opinion it will need to be something that evolves over time. I would suggest that if Mike were to come the maintainer or editor of the docs that we have a well defined process for him to gradually update the doc guidelines (with the community of course) as contributions come in and more docs get written.
Yup, an up front documentation work is an unreasonable request, but when
Mike (or anyone else) distills a new general rule is should be proposed
(if big or potential source of disagreement) and then included in the
doc general rules for everybody to see. Gradually we'll adjust the guide
contents and everyone jumping in will have a head start by reading the
guide.
Cheers
Andrea
Justin Deoliveira ha scritto:
Good question. I would say perhaps say A2, but ammeded to make use of the sphinx 'todo' extension, used to annotate a doc with a list of todo items. Same deal as with confluence.
Wondering about having Sphinx itself checking for broken links and just
failing the build?
I stumbled upon this:
http://bitbucket.org/birkenfeld/sphinx/src/24762d857a19/sphinx/linkcheck.py
which is for external links, but wondering if something similar could be
done for internal ones (or maybe it already exists, thought googling for
it did not return much).
Cheers
Andrea
Mike Pumphrey ha scritto:
I don't think I was trying to suggest that all docs _have_ to go through me, only that I am making myself available should people wish to have someone review.
Don't get me wrong, I wasn't trying to put words in your mails, just
wanted to make sure everybody is on the same base.
In GeoTools a module maintainer is basically a despot and can be overruled only by the PMC, one has to go through her unless
she conceded you free access. I wanted to make
sure the same situation does not repeat in GeoServer.
Cheers
Andrea
--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.
Ahh good point. How do people feel about the .. todo:: ? I've been going back and forth on it. I don't believe it's implemented on any of the projects, currently, unless I just can't find it.
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
Justin Deoliveira wrote:
Good question. I would say perhaps say A2, but ammeded to make use of the sphinx 'todo' extension, used to annotate a doc with a list of todo items. Same deal as with confluence.
Mike Pumphrey wrote:
I was suggesting as much, actually. It doesn't have to be me, of course, but I will gladly volunteer. I don't claim to have any great wisdom when it comes to technical writing, so if someone steps up who pulls rank on me, I'll gladly defer.
One specific aside that I thought of after sending my previous message:
Q: What if I want to create an internal reference, but I haven't actually written the referenced section?
A1: Create the reference, then create a blank reference section (i.e. just the section header, with no content), so that the link verifies and future writers know what the reference is supposed to go to.
A2: Don't create a reference link, and add one in later when the section is added.
(The idea is to prevent broken links)
I'll put this in the docguide too, but just thought I'd throw it out here, as I've caught a bunch of these Links To Nowhere.
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
Justin Deoliveira wrote:
Thanks Mike.
I think it would actually be good to have a pseudo module maintainer for docs. The primary reason being that I think the best way to keep documentation consistent and flowing is to have a single "editor".
I am not sure how others would feel but I would be cool with submitting documentation changes via patch for review if you were cool with it Mike. Interested in how the other devs feel.
-Justin
Mike Pumphrey wrote:
Hi all. This is just a reminder to anyone who is committing changes/updates/additions to the GeoServer documentation to please build the docs and verify that there are no errors, just as you would not commit any code before ensuring that it compiles correctly. I'm happy that people are adding to the docs, but making sure that the project has no warnings/syntax errors ensures a happy place that's more conducive for everyone to contribute. If you have work you'd like to put up for review, you can always file a JIRA and even assign it to me, and I'll do my best to review it for style/legibility, if not actual correctness.
Thanks all, and sorry for the nag. Although, while I'm at it, when's the last time you cleaned your room?
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
BTW, I did a bit of a refresh on the docguide yesterday, adding in some new suggestions posed over the past month or two and filling out most of the empty sections (although if someone (Jody? Alyssa?) would like to populate the section on how to install Sphinx on OS X, that would be nice).
http://docs.geoserver.org/trunk/docguide/
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
Andrea Aime wrote:
Justin Deoliveira ha scritto:
> Agreed on all fronts. I don't think anyone wants to place the docs or
any other part of the system under lock and key subject to one persons whims. As with any contribution there should be a good and documented reason for asking someone to modify or rework something.
Coming up with a complete docguide is no easy task though. In my opinion it will need to be something that evolves over time. I would suggest that if Mike were to come the maintainer or editor of the docs that we have a well defined process for him to gradually update the doc guidelines (with the community of course) as contributions come in and more docs get written.
Yup, an up front documentation work is an unreasonable request, but when
Mike (or anyone else) distills a new general rule is should be proposed
(if big or potential source of disagreement) and then included in the
doc general rules for everybody to see. Gradually we'll adjust the guide
contents and everyone jumping in will have a head start by reading the
guide.
Cheers
Andrea
I found them relatively useful in confluence... especially the ability to aggregate all of them into a single list on the page. Which sphinx supports as well.
Mike Pumphrey wrote:
Ahh good point. How do people feel about the .. todo:: ? I've been going back and forth on it. I don't believe it's implemented on any of the projects, currently, unless I just can't find it.
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
Justin Deoliveira wrote:
Good question. I would say perhaps say A2, but ammeded to make use of the sphinx 'todo' extension, used to annotate a doc with a list of todo items. Same deal as with confluence.
Mike Pumphrey wrote:
I was suggesting as much, actually. It doesn't have to be me, of course, but I will gladly volunteer. I don't claim to have any great wisdom when it comes to technical writing, so if someone steps up who pulls rank on me, I'll gladly defer.
One specific aside that I thought of after sending my previous message:
Q: What if I want to create an internal reference, but I haven't actually written the referenced section?
A1: Create the reference, then create a blank reference section (i.e. just the section header, with no content), so that the link verifies and future writers know what the reference is supposed to go to.
A2: Don't create a reference link, and add one in later when the section is added.
(The idea is to prevent broken links)
I'll put this in the docguide too, but just thought I'd throw it out here, as I've caught a bunch of these Links To Nowhere.
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
Justin Deoliveira wrote:
Thanks Mike.
I think it would actually be good to have a pseudo module maintainer for docs. The primary reason being that I think the best way to keep documentation consistent and flowing is to have a single "editor".
I am not sure how others would feel but I would be cool with submitting documentation changes via patch for review if you were cool with it Mike. Interested in how the other devs feel.
-Justin
Mike Pumphrey wrote:
Hi all. This is just a reminder to anyone who is committing changes/updates/additions to the GeoServer documentation to please build the docs and verify that there are no errors, just as you would not commit any code before ensuring that it compiles correctly. I'm happy that people are adding to the docs, but making sure that the project has no warnings/syntax errors ensures a happy place that's more conducive for everyone to contribute. If you have work you'd like to put up for review, you can always file a JIRA and even assign it to me, and I'll do my best to review it for style/legibility, if not actual correctness.
Thanks all, and sorry for the nag. Although, while I'm at it, when's the last time you cleaned your room?
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
------------------------------------------------------------------------------
_______________________________________________
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.
I couldn't find much of anything on this either, although searching for Sphinx on line is terribly difficult (too many other more popular things named Sphinx). Maybe we can edit the Makefile to abuse people when errors occur...
Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org
Andrea Aime wrote:
Justin Deoliveira ha scritto:
Good question. I would say perhaps say A2, but ammeded to make use of the sphinx 'todo' extension, used to annotate a doc with a list of todo items. Same deal as with confluence.
Wondering about having Sphinx itself checking for broken links and just
failing the build?
I stumbled upon this:
http://bitbucket.org/birkenfeld/sphinx/src/24762d857a19/sphinx/linkcheck.py
which is for external links, but wondering if something similar could be
done for internal ones (or maybe it already exists, thought googling for
it did not return much).
Cheers
Andrea