Everyone wants (someone else) to do it Writing documentation for - - PowerPoint PPT Presentation

Everyone wants (someone else) to do it

Writing documentation for open source software

2

Welcome

Mike Pumphrey Community Advocate mike@boundlessgeo.com github.com/bmmpxf Open Source Geospatial Foundation GeoServer Committer Boundless Boundless provides geospatial tools and services for managing data and building applications. Projects OpenGeo Suite OpenGeo Training GeoServer

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

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

14

Easy - sanity check?

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


• therwise 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

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.

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
• f 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 ...

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

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

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

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

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

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

Translation

43

Tranifex

44

Login and Edit

45

Thanks!