Hi there. I've written up a GSIP (my first!) and would like everyone's feedback on it.
http://geoserver.org/display/GEOS/GSIP+25+-+New+Documentation+Framework
Thanks,
Mike Pumphrey
Outreach Engineer, OpenGeo
Mike Pumphrey ha scritto:
Hi there. I've written up a GSIP (my first!) and would like everyone's feedback on it.
http://geoserver.org/display/GEOS/GSIP+25+-+New+Documentation+Framework
Mumble is it just me, or only DocuWiki can be edited online?
The other two would have to be stored in svn, right?
The parallel structure is ok for me, I'd say, at least the
community contributed docs should be in a wiki.
Choice wise, I would like to avoid anything that requires
a build to see the resulting page, and in particular docbook, tried
it out manually and also with a java based helper editor
(free for docbook), was a pain in both cases.
Cheers
Andrea
I think the community docs would necessarily be in a wiki format. As
for the official canon, I don't think that adding version
control/management would be a bad thing.
The other thing to mention is that one-off docs (GSIPs, etc) would
necessarily not be part of this framework, just the basic docs that
presumably wouldn't be so variable.
That said, if you have other suggestions on tools, I'm happy to hear of them. I really like Sphinx, personally, and its PDF output is magnificent. 
Thanks,
Mike
Andrea Aime wrote:
Mike Pumphrey ha scritto:
Hi there. I've written up a GSIP (my first!) and would like everyone's feedback on it.
http://geoserver.org/display/GEOS/GSIP+25+-+New+Documentation+Framework
Mumble is it just me, or only DocuWiki can be edited online?
The other two would have to be stored in svn, right?
The parallel structure is ok for me, I'd say, at least the
community contributed docs should be in a wiki.Choice wise, I would like to avoid anything that requires
a build to see the resulting page, and in particular docbook, tried
it out manually and also with a java based helper editor
(free for docbook), was a pain in both cases.Cheers
Andrea
tried to comment on the page but it threw an error...
here's my comment
Agree that current situation is sub-optimal. Ideally, IMHO,
documentation ought to be able to be generated easily within each
module and previewed by the module maintainer. If this step doesnt
require a build, but a build actually checked for the presence of the
expected documentation that would help IMHO. This would also allow us
to compare dates of documentation and changes, and automatically
include a per-module list of changes per release tag. The master
documentation should then automatically include each module's doc,
making the whole thing more regulary structured and updated.
I also had a quick look to see how to include a comment submission
form on the page but it wasnt obvious.
Rob A
On Wed, Sep 3, 2008 at 8:21 AM, Mike Pumphrey <mike@anonymised.com> wrote:
I think the community docs would necessarily be in a wiki format. As
for the official canon, I don't think that adding version
control/management would be a bad thing.The other thing to mention is that one-off docs (GSIPs, etc) would
necessarily not be part of this framework, just the basic docs that
presumably wouldn't be so variable.That said, if you have other suggestions on tools, I'm happy to hear of
them. I really like Sphinx, personally, and its PDF output is
magnificent.Thanks,
MikeAndrea Aime wrote:
Mike Pumphrey ha scritto:
Hi there. I've written up a GSIP (my first!) and would like
everyone's feedback on it.http://geoserver.org/display/GEOS/GSIP+25+-+New+Documentation+Framework
Mumble is it just me, or only DocuWiki can be edited online?
The other two would have to be stored in svn, right?
The parallel structure is ok for me, I'd say, at least the
community contributed docs should be in a wiki.Choice wise, I would like to avoid anything that requires
a build to see the resulting page, and in particular docbook, tried
it out manually and also with a java based helper editor
(free for docbook), was a pain in both cases.Cheers
Andrea-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
One thing that just popped up on the -users list, and which I too have messed up completely over at geowebcache.org , is the issue regarding what version documentation applies to.
Ideally I think we'd like "copy-on-change", but since that's probably not realistic I think we should aim for a structure where we copy the entire documentation tree when we release a new version. Of course that will get annoying with minor point releases, which can still contain major upgrades, so I guess we'll have to compromise somehow, but definitely have separate trees.
Anyway, I think it's important to think about this before we start feeding stuff into the new system, whichever one it ends up being. Documentation is a lot of (important) work no matter how you look at it.
-Arne
I think this actually speaks to the advantage of using a system that is stored in SVN. That's one of the limitations of wikis, even confluence, is you can't revision the whole really well.
If it's in svn in sphinx or whatever then whenever we cut a release the docs should be up to date for it. Older versions will have older docs. And for web accessible docs we can have the various versions up 1.6.x, 1.7.x, etc.
C
Arne Kepp wrote:
One thing that just popped up on the -users list, and which I too have messed up completely over at geowebcache.org , is the issue regarding what version documentation applies to.
Ideally I think we'd like "copy-on-change", but since that's probably not realistic I think we should aim for a structure where we copy the entire documentation tree when we release a new version. Of course that will get annoying with minor point releases, which can still contain major upgrades, so I guess we'll have to compromise somehow, but definitely have separate trees.
Anyway, I think it's important to think about this before we start feeding stuff into the new system, whichever one it ends up being. Documentation is a lot of (important) work no matter how you look at it.
-Arne
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
Chris Holmes wrote:
I think this actually speaks to the advantage of using a system that is stored in SVN. That's one of the limitations of wikis, even confluence, is you can't revision the whole really well.
If it's in svn in sphinx or whatever then whenever we cut a release the docs should be up to date for it. Older versions will have older docs. And for web accessible docs we can have the various versions up 1.6.x, 1.7.x, etc.
I am just going to quick contribute to this thread (since having useful docs is a passion of mine :-P).
This is a wild idea that may only appeal to Andrea - something to consider is using the "Almost Plain Text" format:
- Doxia – Introduction
- Doxia – The APT format
It is plain text (and thus able to be used without fancy docbook editors). They have converters to html, pdf, and assorted other flavours. There is an eclipse plugin and so on ...
When the maven dude was at a JUG I went to he referred to a converter from confluence to ATP; but I could not find it with a quick web search...
Jody
Agreed. That's yet another aspect of Ubuntu's documentation that I like.
https://help.ubuntu.com/ (Note the tabs.)
As for versioning, I'm thinking that it's probably a tremendous overhead to have have separate docs for point releases (at least online, we would continue the process we have now of snapshotting the docs for releases), so perhaps we could have different doc branches (1.6, 1.7, 2.0 etc) and caveats on pages like "NOTE: applies to version 1.6.4 and later". That seems functional yet not overly painful.
Still brainstorming here. If anyone else has ideas, I'm keen to hear them.
Mike
Arne Kepp wrote:
One thing that just popped up on the -users list, and which I too have messed up completely over at geowebcache.org , is the issue regarding what version documentation applies to.
Ideally I think we'd like "copy-on-change", but since that's probably not realistic I think we should aim for a structure where we copy the entire documentation tree when we release a new version. Of course that will get annoying with minor point releases, which can still contain major upgrades, so I guess we'll have to compromise somehow, but definitely have separate trees.
Anyway, I think it's important to think about this before we start feeding stuff into the new system, whichever one it ends up being. Documentation is a lot of (important) work no matter how you look at it.
-Arne
A simple solution would be to tag the pages with the version of GeoServer they were written for.
Jody
Mike Pumphrey wrote:
Agreed. That's yet another aspect of Ubuntu's documentation that I like.
https://help.ubuntu.com/ (Note the tabs.)
As for versioning, I'm thinking that it's probably a tremendous overhead to have have separate docs for point releases (at least online, we would continue the process we have now of snapshotting the docs for releases), so perhaps we could have different doc branches (1.6, 1.7, 2.0 etc) and caveats on pages like "NOTE: applies to version 1.6.4 and later". That seems functional yet not overly painful.
Still brainstorming here. If anyone else has ideas, I'm keen to hear them.
Mike
I was checking over this proposal prior to the meeting ...
can we seriously consider "apt" as a format; it is a text format made by the same people that did docbook; and seems way more sane; has an editor (in the form of an eclipse plugin) and has lots of tool support for pdf and html generation (which has now been folded into maven stuff if we even care about that).
Jody
Mike Pumphrey wrote:
Hi there. I've written up a GSIP (my first!) and would like everyone's feedback on it.
http://geoserver.org/display/GEOS/GSIP+25+-+New+Documentation+Framework
Thanks,
Mike Pumphrey
Outreach Engineer, OpenGeo-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
Jody Garnett ha scritto:
I was checking over this proposal prior to the meeting ...
can we seriously consider "apt" as a format; it is a text format made by the same people that did docbook; and seems way more sane; has an editor (in the form of an eclipse plugin) and has lots of tool support for pdf and html generation (which has now been folded into maven stuff if we even care about that).
links?
Cheers
Andrea
I sent links last week but nobody replied to the message - here is the repost:
I am just going to quick contribute to this thread (since having useful docs is a passion of mine :-P).
This is a wild idea that may only appeal to Andrea - something to consider is using the "Almost Plain Text" format:
- Doxia – Introduction
- Doxia – The APT formatIt is plain text (and thus able to be used without fancy docbook editors). They have converters to html, pdf, and assorted other flavours. There is an eclipse plugin and so on ...
When the maven dude was at a JUG I went to he referred to a converter from confluence to ATP; but I could not find it with a quick web search...Jody
Jody Garnett ha scritto:
I was checking over this proposal prior to the meeting ...
can we seriously consider "apt" as a format; it is a text format made by the same people that did docbook; and seems way more sane; has an editor (in the form of an eclipse plugin) and has lots of tool support for pdf and html generation (which has now been folded into maven stuff if we even care about that).
links?
Cheers
Andrea
You do realize that the apt is really similar to the restructured text that Sphinx uses? http://docutils.sourceforge.net/rst.html
Like that aspect seems to be about the same. apt seems more java oriented, and sphinx more python oriented. But I think the sphinx output looks a bit better, at least in the examples of the two that I could find.
C
Jody Garnett wrote:
I sent links last week but nobody replied to the message - here is the repost:
I am just going to quick contribute to this thread (since having useful docs is a passion of mine :-P).
This is a wild idea that may only appeal to Andrea - something to consider is using the "Almost Plain Text" format:
- http://maven.apache.org/doxia/index.html
- http://maven.apache.org/doxia/references/apt-format.htmlIt is plain text (and thus able to be used without fancy docbook editors). They have converters to html, pdf, and assorted other flavours. There is an eclipse plugin and so on ...
When the maven dude was at a JUG I went to he referred to a converter from confluence to ATP; but I could not find it with a quick web search...Jody
Jody Garnett ha scritto:
I was checking over this proposal prior to the meeting ...
can we seriously consider "apt" as a format; it is a text format made by the same people that did docbook; and seems way more sane; has an editor (in the form of an eclipse plugin) and has lots of tool support for pdf and html generation (which has now been folded into maven stuff if we even care about that).
links?
Cheers
Andrea-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
Chris Holmes wrote:
You do realize that the apt is really similar to the restructured text that Sphinx uses? reStructuredText
Yes I do; I was just putting out there as an alternative that has some tool support (eclipse plugin and maven reports).
Like that aspect seems to be about the same. apt seems more java oriented, and sphinx more python oriented. But I think the sphinx output looks a bit better, at least in the examples of the two that I could find.
Thought: It seems like the ideal behavior would be to have clear tagging on the online version of the docs (so people arriving at a page from Google and friends have a clear idea of which version provides the features discussed) but also have the docs browsable by version for those looking from that perspective. Perhaps this could be done by having 'browse docs for x.y.z' links on the main page with filtered versions of the page index, or by having the pdf output filtered by the same metadata used to tag the web version.
-d
Jody Garnett wrote:
A simple solution would be to tag the pages with the version of GeoServer they were written for.
JodyMike Pumphrey wrote:
Agreed. That's yet another aspect of Ubuntu's documentation that I like.
https://help.ubuntu.com/ (Note the tabs.)
As for versioning, I'm thinking that it's probably a tremendous overhead to have have separate docs for point releases (at least online, we would continue the process we have now of snapshotting the docs for releases), so perhaps we could have different doc branches (1.6, 1.7, 2.0 etc) and caveats on pages like "NOTE: applies to version 1.6.4 and later". That seems functional yet not overly painful.
Still brainstorming here. If anyone else has ideas, I'm keen to hear them.
Mike
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel