proj4.org, documentation, and documentation maintenance

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

proj4.org, documentation, and documentation maintenance

Howard Butler-3
All,

The documentation for the proj.4 project has always been in flux, mostly due to proj.4's shared history as a friendly fork. The current situation is a difficult challenge for users looking for information. There's stuff in PDFs, stuff in two different wikis, and stuff in man pages. All of it can be a little bit different, and users are left to figure out what is the top of the heap on their own.

I know that adding *yet another* website by itself to this mix might not really solve the problem, but I think part of the issue has been that it was difficult to maintain a single, streamlined documentation set. To that end, at the Paris Code Sprint [1], I implemented a documentation system based on Sphinx [2], which has stabilized the management of documentation for many other projects in the open source geo space like OpenLayers, MapServer, and GeoTools.

I then adapted work of Even Rouault and Thomas Bonfort from the MapServer project and applied it in proj.4's situation to close the loop on the documentation system. What this means is every pull request that updates documentation will cause the website to be regenerated and refreshed (you can even edit on the GitHub website and make a PR if you want). Combined with the Sphinx organization, it will be easier for the proj.4 project to maintain and deliver coherent documentation.

It is my hope that this approach will allow documentation contributions to easily make it to the canonical website, allow the documentation to be organized more thoroughly, and it will allow multiple documentation output types (HTML, PDF, man, etc) to be easily generated from a central documentation set. There is still plenty of work to do, including organizing things, porting over and merging up docs from the various locations, and deciding on possible output types.

http://proj4.org

Howard

PS, are the original Latex files for the various PS/PDF files available somewhere? It would be really nice to port all of that stuff into a single organized documentation set without having to copy/paste out of PDFs.

[1] https://wiki.osgeo.org/wiki/Paris_Code_Sprint_2016
[2] http://sphinx-doc.org
_______________________________________________
Proj mailing list
[hidden email]
http://lists.maptools.org/mailman/listinfo/proj
Reply | Threaded
Open this post in threaded view
|

Re: proj4.org, documentation, and documentation maintenance

jmckenna
Administrator
Great work Howard.

If anyone else wonders where the source of the docs live:
https://github.com/OSGeo/proj.4/tree/master/docs

Let me know if I can help.

-jeff



On 2016-03-03 12:56 PM, Howard Butler wrote:

> All,
>
> The documentation for the proj.4 project has always been in flux, mostly due to proj.4's shared history as a friendly fork. The current situation is a difficult challenge for users looking for information. There's stuff in PDFs, stuff in two different wikis, and stuff in man pages. All of it can be a little bit different, and users are left to figure out what is the top of the heap on their own.
>
> I know that adding *yet another* website by itself to this mix might not really solve the problem, but I think part of the issue has been that it was difficult to maintain a single, streamlined documentation set. To that end, at the Paris Code Sprint [1], I implemented a documentation system based on Sphinx [2], which has stabilized the management of documentation for many other projects in the open source geo space like OpenLayers, MapServer, and GeoTools.
>
> I then adapted work of Even Rouault and Thomas Bonfort from the MapServer project and applied it in proj.4's situation to close the loop on the documentation system. What this means is every pull request that updates documentation will cause the website to be regenerated and refreshed (you can even edit on the GitHub website and make a PR if you want). Combined with the Sphinx organization, it will be easier for the proj.4 project to maintain and deliver coherent documentation.
>
> It is my hope that this approach will allow documentation contributions to easily make it to the canonical website, allow the documentation to be organized more thoroughly, and it will allow multiple documentation output types (HTML, PDF, man, etc) to be easily generated from a central documentation set. There is still plenty of work to do, including organizing things, porting over and merging up docs from the various locations, and deciding on possible output types.
>
> http://proj4.org
>
> Howard
>
> PS, are the original Latex files for the various PS/PDF files available somewhere? It would be really nice to port all of that stuff into a single organized documentation set without having to copy/paste out of PDFs.
>
> [1] https://wiki.osgeo.org/wiki/Paris_Code_Sprint_2016
> [2] http://sphinx-doc.org
> _______________________________________________

--
Jeff McKenna
MapServer Consulting and Training Services
http://www.gatewaygeomatics.com/
_______________________________________________
Proj mailing list
[hidden email]
http://lists.maptools.org/mailman/listinfo/proj
Reply | Threaded
Open this post in threaded view
|

Re: proj4.org, documentation, and documentation maintenance

Tom Kralidis
In reply to this post by Howard Butler-3
Great job Howard! Great to see these improvements.

..Tom

On Thu, Mar 3, 2016 at 11:56 AM, Howard Butler <[hidden email]> wrote:

> All,
>
> The documentation for the proj.4 project has always been in flux, mostly due to proj.4's shared history as a friendly fork. The current situation is a difficult challenge for users looking for information. There's stuff in PDFs, stuff in two different wikis, and stuff in man pages. All of it can be a little bit different, and users are left to figure out what is the top of the heap on their own.
>
> I know that adding *yet another* website by itself to this mix might not really solve the problem, but I think part of the issue has been that it was difficult to maintain a single, streamlined documentation set. To that end, at the Paris Code Sprint [1], I implemented a documentation system based on Sphinx [2], which has stabilized the management of documentation for many other projects in the open source geo space like OpenLayers, MapServer, and GeoTools.
>
> I then adapted work of Even Rouault and Thomas Bonfort from the MapServer project and applied it in proj.4's situation to close the loop on the documentation system. What this means is every pull request that updates documentation will cause the website to be regenerated and refreshed (you can even edit on the GitHub website and make a PR if you want). Combined with the Sphinx organization, it will be easier for the proj.4 project to maintain and deliver coherent documentation.
>
> It is my hope that this approach will allow documentation contributions to easily make it to the canonical website, allow the documentation to be organized more thoroughly, and it will allow multiple documentation output types (HTML, PDF, man, etc) to be easily generated from a central documentation set. There is still plenty of work to do, including organizing things, porting over and merging up docs from the various locations, and deciding on possible output types.
>
> http://proj4.org
>
> Howard
>
> PS, are the original Latex files for the various PS/PDF files available somewhere? It would be really nice to port all of that stuff into a single organized documentation set without having to copy/paste out of PDFs.
>
> [1] https://wiki.osgeo.org/wiki/Paris_Code_Sprint_2016
> [2] http://sphinx-doc.org
> _______________________________________________
> Proj mailing list
> [hidden email]
> http://lists.maptools.org/mailman/listinfo/proj
_______________________________________________
Proj mailing list
[hidden email]
http://lists.maptools.org/mailman/listinfo/proj