Everyone wants (someone else) to do it Writing documentation for open source software
Welcome Mike Pumphrey Projects Community Advocate OpenGeo Suite mike@boundlessgeo.com OpenGeo Training github.com/bmmpxf GeoServer Open Source Geospatial Foundation GeoServer Committer Boundless Boundless provides geospatial tools and services for managing data and building applications. 2
Welcome Jody Garnett Open Source Projects Community Lead GeoTools jgarnett@boundlessgeo.com GeoServer @jodygarnett uDig Eclipse Foundation LocationTech Project Steering Committee LocationTech Technology Project Open Source Geospatial Foundation OSGeo Incubation Chair Boundless GeoTools Project O ffi cer Boundless provides geospatial tools and services for managing data and building applications. 3
Getting Started 4
What we are up against here • If you spent $30,000 on a software package – you might spend a week figuring out how it works • If you spend $0 on an open source project how much time are you going to spend? – 5 mins? – 10 mins? – 15 mins? 5
Documentation Priorities • Installation – Ensure potential users can install your software • Quick start – And see their own data 6
Installation • Get the software installed • Show each step – this is used as a sanity check to tell if everything is going okay • Do not get distracted by explaining options – don't waste time – your software is being evaluated 7
Installation Video? • Great! – very friendly – shows the software working ... providing hope! • Caution: – It can be hard to find a video that matches the version of the software you are using – Scrubbing a video back and forth to catch a key installation step is frustrating • Recommend – video for promotion showing individual features – documentation for installation 8
Quickstart! • Show, do not tell – Focus on the key "value add" for your software • Think "internet" attention spans here – Don't distract with background stories – Get something on screen and then explain why it is amazing 9
Stack Exchange? • Stack exchange is a Q&A site that is popular with geoserver and geotools users • It is more an alternative to the user email list than the documentation – Questions that get asked repeatedly... may point out a hole in the documentation? – Stack Exchange is good at staying current ... but you may be using an old version? 10
Writing Tips and Tricks 11
EASY • Please do not use the word EASY – The only that can happen here is to make people FEEL FRUSTRATED when they have trouble • They probably are having trouble because – you wrote this sentence three years ago before windows 8 confused the start menu? – Or last month before the start menu came back? 12
SIMPLE or SIMPLY • Please do not use the word "simple" – The only thing that can happen is to make people FEEL STUPID when they do not understand what you are talking about • A piece of software on its own is complex – When combined with other software ... more complex – When on a future operating system ... more complex 13
Easy - sanity check? 14
Simple - sanity check 15
Setting Expectations • Focus on getting any content – Do not let PERFECT be the enemy of GOOD – do not let GOOD be the benefit of NOTHING • Do not worry about things like grammer 16
Curation 17
Example: GeoExt Styler 18
Example: GeoFence GUI 19
Example: Complex Features 20
How did this happen? • Easy to forget about: – documentation – quality assurance • Project has been going a long time – Developers can 'hope' to get back to something – Without a champion features get dropped • Features produced under contract – Great social pressure to include features in next release (so team can get paid) – But risk team moving on to other work (and assuming a "volunteer" will get to it) 21
What did not work • Let the community deal with it - wiki! • GeoTools: – Gave up on wiki, – found that jody had written 90% of the wiki – Code examples especially were out of date causing more confusion then help • GeoServer: • OpenGeo migrated to a fresh set of docs as part of OpenGeo Suite product initiative 22
What has Worked • Boundless policy – a feature is "not DONE until it is documented" ! • Mike – Ask developer to write the low-level, and the Mike translates for the world – Interview the developer and translate the result • Jody – Included the cost upfront in GeoTools proposal ( i.e. process “tasks” section ) – write the docs for features that would otherwise not be merged in 23
Policy Change • Supported "Extensions" now require – documentation and QA test coverage • Change control requests now require: – Documentation and QA to be included up front! • Success? – Our docs now do a much better job of documenting new features – Consultants now know what is required up front! (and communicate to customers?) – This is a barrier to "casual" drive by GitHub commits 24
GeoServer Documentation Story • Documentation was originally html! • Moved from HTML to wiki – Outreach attempt to community! – Gradually became out of date • Moved from wiki to codebase • Mike volunteer as “editor” – Set expectations 25
GeoTools Documentation Story • Started in "docbook" – XML format of doom! • Moved to CodeHaus "wiki" – Wiki's needed an editor to be successful – After 10 years editor had written 90% of the docs – vandalism because we cannot have nice things • Moved to codebase – Harder for community volunteers than wiki – But now versioned alongside releases! – Initial port in "pandoc", then six months to clean up the mess 26
RST and Sphinx Migrating from WIKI to CodeBase 27
Sphinx • Install Python • easy_instal sphinx • make html make html mkdir -p build/html build/doctrees sphinx-build -b html -d build/doctrees source build/html Running Sphinx v1.2.2 loading pickled environment... not yet created building [html]: targets for 438 source files that are out of date updating environment: 438 added, 0 changed, 0 removed reading sources... [100%] webadmin/tilecache/layers ... Build finished. The HTML pages are in build/html. 28
RST • Use "Rich Structured Text" wiki syntax Background ========== Welcome! From all of the GeoServer users and developers, we are happy to see that you have an interest in contributing to the GeoServer documentation. Whether it's the fix of a typo or a whole new collection of pages, all contributions are appreciated. With your help we can make GeoServer documentation helpful and robust, and thus make GeoServer a better product. Writing Documentation --------------------- GeoServer documentation written in `reStructuredText <http:// docutils.sourceforge.net/rst.html>`_ , a lightweight markup syntax, and built into HTML and PDF content using `Sphinx <http://sphinx.pocoo.org>`_ , a documentation framework written by the developers of Python. In this way, the documentation could be merged with the source code of GeoServer ... 29
In-line Code Examples • This is the "killer feature" for GeoTools Quickstart Application ---------------------- Now that your environment is setup we can put together a simple Quickstart. This example will display a shapefile on screen. #. Create the package org.geotools.tutorial.quickstart using your IDE. #. Create the org.geotools.tutorial.quickstart.Quickstart class using your IDE. .. image:: images/class.jpg :scale: 60 #. Fill in the following code: .. literalinclude:: /../src/main/java/org/geotools/tutorial/quickstart/ Quickstart.java :language: java 30
Quickfix Edit directly in GitHub 31
Step 1 • Browse the documentation source code directly on the GitHub website: – https://github.com/geoserver/geoserver/tree/master/ doc/en – https://github.com/geoserver/geoserver/tree/master/ doc/es – https://github.com/geoserver/geoserver/tree/master/ doc/fr 32
Step 2 • Navigate to the file you wish to change and click the edit icon 33
Step 3 • Use the editor to modify the file 34
Step 4 • Scroll to the bottom of the page, provide a commit comment and submit. • GitHub will: – Create a fork and submit a pull request on your behalf; or – Immediately make the change for those with commit access 35
Style Guide GeoServer Style Guide 36
Why a Style Guide? • Help community present a "consistent voice" when writing documentation • Additional benefits: – Can help an editor be fair and consistent – Provide a link to page of good/bad examples when reviewing a pull request 37
Be concise • Documentation should be concise (and not just a brain dump.) • Reference material – Short pages and be easy to refer to – No scrolling through large volumes of text) • Tutorials can be longer, depending on scope • Want to share your thoughts and insights? – Write a blog post (or twitter for small thoughts) • Documentation is a manual, not a wiki. 38
Recommend
More recommend