New documentation launched

I’m excited to tell you about some changes to the GeoServer documentation. We are transitioning away from our wiki in favor of a new system. After much discussion, we are now using the Sphinx Documentation Generator.

Sphinx has many advantages over a wiki. The biggest advantage is that the content of the documentation is written in plain text (using a simple markup language called reStructuredText) and then “compiled” to become the finished product. With documentation now essentially just another part of the source code, it can be brought under version control. This means that we can, for the first time, have version-specific documentation, as well as the ability to allow for simultaneous editing, conflict management, and all of the other tools associated with version control.

While wikis have many advantages, a clear hierarchy is generally not one of them. (For example, one doesn’t read Wikipedia “from the beginning.”) And while search remains a feature of our documentation, Sphinx is geared towards the creation of text that can be constructed and read like a manual. Along this line, we can now create documentation in PDF, a feature that has been asked about for years.

We have soft launched the new documentation with the release of GeoServer 1.7.4. The old wiki is still live, and will remain so. But there is still much to be done, and you can help. The documentation is still very much a work in progress, and not all of the content from the wiki has been migrated. We’ve developed a guide to documentation that describes the ways that you can contribute. The most helpful way is to create content for empty or unfinished pages, and either submit a bug report with the content attached or commit the changes on your own. (If you are interested in getting commit rights to our documentation, please send an email to the GeoServer developers mailing list.) If you are aware of a page in the wiki that should be migrated to the new site, please let us know as well.

For GeoServer 1.7.4, the documentation download contains both HTML and PDF output. I encourage everyone to download, read, and make suggestions. For our part, we will continue to work to make GeoServer easy to learn, use, and understand.

5 Comments

  1. Leif
    Posted May 6, 2009 at 10:26 am | Permalink

    Glad to hear you’re happy with your new doc system. The resulting PDF looks very nice.

    In defense of wiki’s though…maybe it wasn’t the fact you were *using* a wiki but *which* wiki you were using. For example we use MoinMoin and it can export pages to PDF and it stores all wiki pages as flat text files.

    Cheers

  2. Leif
    Posted May 6, 2009 at 10:33 am | Permalink

    I think i misunderstood the flat/plain text part of your post in my last comment.

    I handle a lot of documentation internally at my job so I have a couple questions because I too have debated the wiki vs. other forms of releasing docs. The advantage obviously being that a PDF is static and can be archived and referenced for older versions. But the disadvantage is that it’s …static. With the wiki (or any web based documentation for that matter) fixing a typo here or there or correcting instructions is as simple as making the change and clicking save. The next time someone views the web docs they see the latest version. Are you planning on generating and releasing a new version of the PDF doc everytime there is a typo?

  3. Mike Pumphrey
    Posted May 6, 2009 at 5:20 pm | Permalink

    Hi Leif. Thanks for your comments. The plan is to generate PDF files only for each release. The HTML pages, on the other hand, are generated and updated nightly, as part of the same process that creates the nightly software builds. HTML pages will also be tagged and archived for each release. So releases will have HTML and PDF version, but the most recent version will be HTML only.

  4. leche
    Posted July 16, 2009 at 6:39 pm | Permalink

    Hi,

    I have got geoserver properly installed, Udis and other open source softwareslike PotsGIS, QGIS. I configured Geoserver and see the maps I created with the http://hocalhost:8080/geoserver.
    I was wondering if someone could tell me how I can configure geoserver to see the map on our company website.

    I am sorry for such question but I am new and with no programming or development skills.

    Yours sincerely

    leche

  5. Posted December 19, 2009 at 11:42 am | Permalink

    Hi, Congratulations for the project! The Geoserver project is changing the WebGis World.

    We would like to share the Geoserver 1.7 User Manual translation for portuguese that we are using. We also have a small group of exercises that we would like to share in order to divulgate and “spread” Geoserver around the portuguese GIS community. How can I do this?

    We are also working in User Manual for Geoserver 2.0 version…

    Thanks,
    Nelson Mileu

Download GeoServer