[Geoserver-devel] a couple of website glitches

GeoServer GeoServer Developer
1

Rounding them up here, rather than a bug report ...

http://geoserver.org/release/master/
- lists 2.10 not 2.11

http://geoserver.org/release/2.10.x/
- correct nightly build, but does not link to community modules

http://geoserver.org/release/2.9.x/
http://geoserver.org/release/stable/
http://geoserver.org/release/maintain/
- looks good!
--
Jody Garnett

Somewhat relatedly, that reminds me https://osgeo-org.atlassian.net/browse/GEOS-7786 was marked 'resolved' but has not really been addressed. The specific issue itself may not matter greatly, but I'm bringing it up because it could hint at a couple general documentation-tweaks that might be beneficial.

I'm happy to submit changes to address this, but I may need some guidance on the best approach in doing so. That's the reason I'm asking here.

Quick summary: the top-ranked web-search result for the terms 'geoserver wps plugin' returns a v2.3.4 docs page that has broken links. Although old docs are not a problem in and of themselves, keeping rotting links sitting around cannot reflect well on Geoserver's image, especially for those just getting started who might - for example - be trying to figure out how to get WPS working for their own stacks. On top of running into broken links, users are even more likely to hit gotchas when Geoserver documentation does not make it easy to navigate between available documentation-versions.

Potential immediate solutions to the issue linked above:

  A. Affected documentation-pages across version-branches could be edited to point to the modern Download and About pages.
  
  B. Redirects at the affected links could be configured so all versions of the documentation that point to the bad links will be fixed in a single swoop just by placing the redirect. (The problem-children of which I'm aware are the old About and Download links - http://geoserver.org/display/GEOS/What+is+Geoserver and http://geoserver.org/display/GEOS/Download respectively.)

  C1. Pages for **unsupported** plugins could have warnings added so users know that installing them against a modern Geoserver version might require some hacking. The notices could also suggest that users +adopt+ said plugins.

  C2. Old documentation-pages **in general** might also have warnings, so users at the very least understand the risks of referring to those pages rather than the current ones. These risks of course include being frustrated by dead links, among other things.

More generally:

  Although versioned documentation is very common, most other projects allow jumping between parallel documentation-pages for different versions of a given platform/API/language/library/etc. I think Geoserver's docs could benefit from this, which would also serve to alleviate some of the problems potentially caused by search-engines indexing arbitrary pages and (often) linking to older URLs which may no longer feature the best information about a given subject.

Feedback appreciated.

- Patrick O'Toole

Application Developer
Wyoming Natural Diversity Database
UW Berry Biodiversity Conservation Center
Department 3381, 1000 E. University Av.
Laramie, WY 82071
P: 307-766-3018

2

Reading this I wonder if we should remove prior versions of the docs; since they are available for download? It is kind of nice when running an older version of GeoServer to look up the docs for just what you need … but as a community we do better to work with (and funding) the latest release :slight_smile:

Do you have an example of “jumping between parallel documentation-pages” Patrick? I know when looking into Tomcat issues recently I always ended up back in the Tomcat 4 documentation when doing a web search (so this issue is not unique to GeoServer).

···

On 25 January 2017 at 00:54, P O’Toole <P.OToole@anonymised.com> wrote:

Rounding them up here, rather than a bug report …

http://geoserver.org/release/master/

  • lists 2.10 not 2.11

http://geoserver.org/release/2.10.x/

  • correct nightly build, but does not link to community modules

http://geoserver.org/release/2.9.x/
http://geoserver.org/release/stable/
http://geoserver.org/release/maintain/

  • looks good!
    –
    Jody Garnett

Somewhat relatedly, that reminds me https://osgeo-org.atlassian.net/browse/GEOS-7786 was marked ‘resolved’ but has not really been addressed. The specific issue itself may not matter greatly, but I’m bringing it up because it could hint at a couple general documentation-tweaks that might be beneficial.

I’m happy to submit changes to address this, but I may need some guidance on the best approach in doing so. That’s the reason I’m asking here.

Quick summary: the top-ranked web-search result for the terms ‘geoserver wps plugin’ returns a v2.3.4 docs page that has broken links. Although old docs are not a problem in and of themselves, keeping rotting links sitting around cannot reflect well on Geoserver’s image, especially for those just getting started who might - for example - be trying to figure out how to get WPS working for their own stacks. On top of running into broken links, users are even more likely to hit gotchas when Geoserver documentation does not make it easy to navigate between available documentation-versions.

Potential immediate solutions to the issue linked above:

A. Affected documentation-pages across version-branches could be edited to point to the modern Download and About pages.

B. Redirects at the affected links could be configured so all versions of the documentation that point to the bad links will be fixed in a single swoop just by placing the redirect. (The problem-children of which I’m aware are the old About and Download links - http://geoserver.org/display/GEOS/What+is+Geoserver and http://geoserver.org/display/GEOS/Download respectively.)

C1. Pages for unsupported plugins could have warnings added so users know that installing them against a modern Geoserver version might require some hacking. The notices could also suggest that users +adopt+ said plugins.

C2. Old documentation-pages in general might also have warnings, so users at the very least understand the risks of referring to those pages rather than the current ones. These risks of course include being frustrated by dead links, among other things.

More generally:

Although versioned documentation is very common, most other projects allow jumping between parallel documentation-pages for different versions of a given platform/API/language/library/etc. I think Geoserver’s docs could benefit from this, which would also serve to alleviate some of the problems potentially caused by search-engines indexing arbitrary pages and (often) linking to older URLs which may no longer feature the best information about a given subject.

Feedback appreciated.

  • Patrick O’Toole

Application Developer
Wyoming Natural Diversity Database
UW Berry Biodiversity Conservation Center
Department 3381, 1000 E. University Av.
Laramie, WY 82071
P: 307-766-3018

Check out the vibrant tech community on one of the world’s most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot

Geoserver-devel mailing list
Geoserver-devel@anonymised.com.366…sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

–
Jody Garnett

3

Reading this I wonder if we should remove prior versions of the docs; since they are available for download? It is kind of nice when running an older version of GeoServer to look up the docs for just what you need … but as a community we do better to work with (and funding) the latest release :slight_smile:

Do you have an example of “jumping between parallel documentation-pages” Patrick? I know when looking into Tomcat issues recently I always ended up back in the Tomcat 4 documentation when doing a web search (so this issue is not unique to GeoServer).

The PostgreSQL docs are an easy concrete example of the way I was thinking, and probably resemble how it might be approached if going the route of keeping all Geoserver docs versions online and just making the addition of cross-links between versions.

A set that I know had some changes between versions: https://www.postgresql.org/docs/9.4/static/sql-createindex.html to https://www.postgresql.org/docs/9.5/static/sql-createindex.html. The core Python documentation is similar (though they use a dropdown-menu instead of a list of hyperlinks). The docs for much of Microsoft’s DotNet stuff are also in the same vein.

Other projects provide a single set of documentation-pages with notes about how (and when) certain behaviors or requirements changed, or first became available. Mozilla Developer Network does this. Same with w3schools.com and php.net. This prevents search-engines from leading people to outdated versions of the documentation, but has the disadvantage of getting cluttered/confusing if a given component has really major changes and shares little in common with its previous incarnations — I don’t know how likely/common this is with Geoserver and its various addons and extensions.

I think the first option of just linking between versions is a bit simpler to manage and probably requires less effort to transition to than the other option, although it does burden readers with the responsibility to navigate to the version that applies to them if linked to the correct topic but a different version that the one they use. The second option removes this burden in exchange for requiring more attention to notes about new/deprecated parameters, invocations, dependencies, etc., etc. It also has the side-effect of making it easier to understand changes between versions, which may be an important activity even though it’s probably not the most common type of interaction with the docs.

I’m be glad to roll up my sleeves and get behind either effort.

  • Patrick
···

Reading this I wonder if we should remove prior versions of the docs; since they are available for download? It is kind of nice when running an older version of GeoServer to look up the docs for just what you need … but as a community we do better to work with (and funding) the latest release :slight_smile:

Do you have an example of “jumping between parallel documentation-pages” Patrick? I know when looking into Tomcat issues recently I always ended up back in the Tomcat 4 documentation when doing a web search (so this issue is not unique to GeoServer).

–

Jody Garnett

On 25 January 2017 at 00:54, P O’Toole <P.OToole@…4506…> wrote:

Rounding them up here, rather than a bug report …

http://geoserver.org/release/master/

  • lists 2.10 not 2.11

http://geoserver.org/release/2.10.x/

  • correct nightly build, but does not link to community modules

http://geoserver.org/release/2.9.x/
http://geoserver.org/release/stable/
http://geoserver.org/release/maintain/

  • looks good!
    –
    Jody Garnett

Somewhat relatedly, that reminds me https://osgeo-org.atlassian.net/browse/GEOS-7786 was marked ‘resolved’ but has not really been addressed. The specific issue itself may not matter greatly, but I’m bringing it up because it could hint at a couple general documentation-tweaks that might be beneficial.

I’m happy to submit changes to address this, but I may need some guidance on the best approach in doing so. That’s the reason I’m asking here.

Quick summary: the top-ranked web-search result for the terms ‘geoserver wps plugin’ returns a v2.3.4 docs page that has broken links. Although old docs are not a problem in and of themselves, keeping rotting links sitting around cannot reflect well on Geoserver’s image, especially for those just getting started who might - for example - be trying to figure out how to get WPS working for their own stacks. On top of running into broken links, users are even more likely to hit gotchas when Geoserver documentation does not make it easy to navigate between available documentation-versions.

Potential immediate solutions to the issue linked above:

A. Affected documentation-pages across version-branches could be edited to point to the modern Download and About pages.

B. Redirects at the affected links could be configured so all versions of the documentation that point to the bad links will be fixed in a single swoop just by placing the redirect. (The problem-children of which I’m aware are the old About and Download links - http://geoserver.org/display/GEOS/What+is+Geoserver and http://geoserver.org/display/GEOS/Download respectively.)

C1. Pages for unsupported plugins could have warnings added so users know that installing them against a modern Geoserver version might require some hacking. The notices could also suggest that users +adopt+ said plugins.

C2. Old documentation-pages in general might also have warnings, so users at the very least understand the risks of referring to those pages rather than the current ones. These risks of course include being frustrated by dead links, among other things.

More generally:

Although versioned documentation is very common, most other projects allow jumping between parallel documentation-pages for different versions of a given platform/API/language/library/etc. I think Geoserver’s docs could benefit from this, which would also serve to alleviate some of the problems potentially caused by search-engines indexing arbitrary pages and (often) linking to older URLs which may no longer feature the best information about a given subject.

Feedback appreciated.

  • Patrick O’Toole

Application Developer
Wyoming Natural Diversity Database
UW Berry Biodiversity Conservation Center
Department 3381, 1000 E. University Av.
Laramie, WY 82071
P: 307-766-3018

Check out the vibrant tech community on one of the world’s most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot

Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

4

I’m a a little late to the game here, but couldn’t the robots.txt be set to Disallow searching any docs that are not “stable” or “nightly”?

The robots.txt standard doesn’t have a good way of doing “allow” so you’d need to update the robots.txt to contain a link to all docs for specific versions - could probably be automated to update with any new release.

Alternatively a copy of all specific versions of docs could be put in a /historical/ subfolder and that alone would need to be added to robots.txt as Dissallowed, but could be linked to as needed by others.

That way the historical docs can remain online which I’ve found useful in the past, and the search engines will only keep links to the current/stable versions.

Does that seem workable?

···

On 26/01/2017 19:44, P O’Toole wrote:

Reading this I wonder if we should remove prior versions of the docs; since they are available for download? It is kind of nice when running an older version of GeoServer to look up the docs for just what you need … but as a community we do better to work with (and funding) the latest release :slight_smile:

Do you have an example of “jumping between parallel documentation-pages” Patrick? I know when looking into Tomcat issues recently I always ended up back in the Tomcat 4 documentation when doing a web search (so this issue is not unique to GeoServer).

The PostgreSQL docs are an easy concrete example of the way I was thinking, and probably resemble how it might be approached if going the route of keeping all Geoserver docs versions online and just making the addition of cross-links between versions.

A set that I know had some changes between versions: https://www.postgresql.org/docs/9.4/static/sql-createindex.html to https://www.postgresql.org/docs/9.5/static/sql-createindex.html. The core Python documentation is similar (though they use a dropdown-menu instead of a list of hyperlinks). The docs for much of Microsoft’s DotNet stuff are also in the same vein.

Other projects provide a single set of documentation-pages with notes about how (and when) certain behaviors or requirements changed, or first became available. Mozilla Developer Network does this. Same with w3schools.com and php.net. This prevents search-engines from leading people to outdated versions of the documentation, but has the disadvantage of getting cluttered/confusing if a given component has really major changes and shares little in common with its previous incarnations — I don’t know how likely/common this is with Geoserver and its various addons and extensions.

I think the first option of just linking between versions is a bit simpler to manage and probably requires less effort to transition to than the other option, although it does burden readers with the responsibility to navigate to the version that applies to them if linked to the correct topic but a different version that the one they use. The second option removes this burden in exchange for requiring more attention to notes about new/deprecated parameters, invocations, dependencies, etc., etc. It also has the side-effect of making it easier to understand changes between versions, which may be an important activity even though it’s probably not the most common type of interaction with the docs.

I’m be glad to roll up my sleeves and get behind either effort.

  • Patrick

From: Jody Garnett [mailto:jody.garnett@anonymised.com]
Sent: Thursday, January 26, 2017 11:47 AM
To: P O’Toole P.OToole@anonymised.com
Cc: geoserver-devel@lists.sourceforge.net
Subject: Re: [Geoserver-devel] a couple of website glitches

Reading this I wonder if we should remove prior versions of the docs; since they are available for download? It is kind of nice when running an older version of GeoServer to look up the docs for just what you need … but as a community we do better to work with (and funding) the latest release :slight_smile:

Do you have an example of “jumping between parallel documentation-pages” Patrick? I know when looking into Tomcat issues recently I always ended up back in the Tomcat 4 documentation when doing a web search (so this issue is not unique to GeoServer).

–

Jody Garnett

On 25 January 2017 at 00:54, P O’Toole <P.OToole@anonymised.com> wrote:

Rounding them up here, rather than a bug report …

http://geoserver.org/release/master/

  • lists 2.10 not 2.11

http://geoserver.org/release/2.10.x/

  • correct nightly build, but does not link to community modules

http://geoserver.org/release/2.9.x/
http://geoserver.org/release/stable/
http://geoserver.org/release/maintain/

  • looks good!
    –
    Jody Garnett

Somewhat relatedly, that reminds me https://osgeo-org.atlassian.net/browse/GEOS-7786 was marked ‘resolved’ but has not really been addressed. The specific issue itself may not matter greatly, but I’m bringing it up because it could hint at a couple general documentation-tweaks that might be beneficial.

I’m happy to submit changes to address this, but I may need some guidance on the best approach in doing so. That’s the reason I’m asking here.

Quick summary: the top-ranked web-search result for the terms ‘geoserver wps plugin’ returns a v2.3.4 docs page that has broken links. Although old docs are not a problem in and of themselves, keeping rotting links sitting around cannot reflect well on Geoserver’s image, especially for those just getting started who might - for example - be trying to figure out how to get WPS working for their own stacks. On top of running into broken links, users are even more likely to hit gotchas when Geoserver documentation does not make it easy to navigate between available documentation-versions.

Potential immediate solutions to the issue linked above:

A. Affected documentation-pages across version-branches could be edited to point to the modern Download and About pages.

B. Redirects at the affected links could be configured so all versions of the documentation that point to the bad links will be fixed in a single swoop just by placing the redirect. (The problem-children of which I’m aware are the old About and Download links - http://geoserver.org/display/GEOS/What+is+Geoserver and http://geoserver.org/display/GEOS/Download respectively.)

C1. Pages for unsupported plugins could have warnings added so users know that installing them against a modern Geoserver version might require some hacking. The notices could also suggest that users +adopt+ said plugins.

C2. Old documentation-pages in general might also have warnings, so users at the very least understand the risks of referring to those pages rather than the current ones. These risks of course include being frustrated by dead links, among other things.

More generally:

Although versioned documentation is very common, most other projects allow jumping between parallel documentation-pages for different versions of a given platform/API/language/library/etc. I think Geoserver’s docs could benefit from this, which would also serve to alleviate some of the problems potentially caused by search-engines indexing arbitrary pages and (often) linking to older URLs which may no longer feature the best information about a given subject.

Feedback appreciated.

  • Patrick O’Toole

Application Developer
Wyoming Natural Diversity Database
UW Berry Biodiversity Conservation Center
Department 3381, 1000 E. University Av.
Laramie, WY 82071
P: 307-766-3018

Check out the vibrant tech community on one of the world’s most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot

Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! [http://sdm.link/slashdot](http://sdm.link/slashdot)

_______________________________________________
Geoserver-devel mailing list
[Geoserver-devel@lists.sourceforge.net](mailto:Geoserver-devel@lists.sourceforge.net)
[https://lists.sourceforge.net/lists/listinfo/geoserver-devel](https://lists.sourceforge.net/lists/listinfo/geoserver-devel)