Upload
jody-garnett
View
666
Download
0
Embed Size (px)
Citation preview
2
WelcomeMike Pumphrey Community Advocate [email protected] 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
WelcomeJody Garnett Community Lead [email protected] @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
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
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
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
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
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 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 ...
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
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 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
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