Everyone wants (someone else) to do it: writing documentation for open source software.
•
1 like•925 views
Many people will cite how their adoption of software was based on the quality of documentation, and yet documentation can be one of the largest gaps in quality with an open source project. This talk will discuss why that is, what you (yes you) can do about it, and how the author has so far managed to avoid burnout by learning to accept less-than-perfect grammar. A FOSS4G 2015 Presentation
Recommended
More Related Content
What's hot
What's hot (20)
Viewers also liked
Similar to Everyone wants (someone else) to do it: writing documentation for open source software.
Similar to Everyone wants (someone else) to do it: writing documentation for open source software. (20)
More from Jody Garnett
More from Jody Garnett (20)
Recently uploaded
Recently uploaded (20)
Everyone wants (someone else) to do it: writing documentation for open source software.
- 1. Everyone wants (someone else) to do it Writing documentation for open source software
- 2. 2 Welcome Mike Pumphrey Community Advocate mike@boundlessgeo.com github.com/bmmpxf Open Source Geospatial Foundation GeoServer CommitterBoundless Boundless provides geospatial tools and services for managing data and building applications. Projects OpenGeo Suite OpenGeo Training GeoServer
- 3. 3 Welcome Jody Garnett Community Lead jgarnett@boundlessgeo.com @jodygarnett Open Source Geospatial Foundation OSGeo Incubation Chair GeoTools Project Officer Eclipse Foundation LocationTech Project Steering Committee LocationTech Technology Project Boundless Boundless provides geospatial tools and services for managing data and building applications. Open Source Projects GeoTools GeoServer uDig
- 5. 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
- 6. Documentation Priorities • Installation – Ensure potential users can install your software • Quick start – And see their own data 6
- 7. 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
- 8. 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
- 9. 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
- 10. 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
- 11. Writing Tips and Tricks 11
- 12. 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
- 13. 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
- 14. 14 Easy - sanity check?
- 15. Simple - sanity check 15
- 16. 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
- 17. Curation 17
- 21. 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
- 22. 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
- 23. 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
- 24. 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
- 25. 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
- 26. 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
- 27. RST and Sphinx Migrating from WIKI to CodeBase 27
- 28. Sphinx • Install Python • easy_instal sphinx • make html 28 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.
- 29. RST • Use "Rich Structured Text" wiki syntax 29 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 ...
- 30. In-line Code Examples • This is the "killer feature" for GeoTools 30 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
- 31. Quickfix Edit directly in GitHub 31
- 32. 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
- 33. Step 2 • Navigate to the file you wish to change and click the edit icon 33
- 34. Step 3 • Use the editor to modify the file 34
- 35. 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
- 36. Style Guide GeoServer Style Guide 36
- 37. 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
- 38. 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
- 39. Avoid marketing • Want to showcase a new feature? – Write an article or a blog post about it. – If it is necessary to point out a technical benefit of a feature then do so from a technical standpoint. • Bad – Super-overlays are a great way to publish super cool datasets awesomely in Google Earth! • Good – Super-overlays allow you to efficiently publish data via Google Earth. 39
- 40. Be professional • Avoid the use of slang or “colorful” language: – The point of a technical document is to be informative, not to keep the reader amused. – Avoiding slang helps keep the document accessible to as large an audience as possible. • Bad – Next, fire up whatever tool you use to browse the web and point it in the direction of ... • Good – Next, start your web browser and navigate to ... 40
- 41. Use direct commands • When providing step-by-step instructions, use direct commands or requests – Avoid the use of “we” and “let’s”. • Bad – Now let’s add a shapefile by ... • Good – Add a shapefile by ... 41
- 42. Naming Conventions • Be consistent • GeoServer uses wikipedia policy: – Capitalization of page names – Capitalization of section names – Verbs like "creating" rather than "create". – Avoid plurals 42
- 43. Translation 43
- 44. Tranifex 44
- 46. Thanks!