1 of 18

Quickstart Review

15 September 2019

2 of 18

Rating guide

  • Looked at 49 Quickstart guides
  • Version 13
  • Awarded 1 point each for existence of:
    • Introduction
    • Quickstart steps
    • Things to try
    • Next steps
  • Subtracted points for:
    • Major re-write required
    • Minor changes required
    • More info required
  • Maximum possible score of 4.

None scored 4 because none are perfect!

3 of 18

Summary of results

Score

Count of Quickstarts

3.5

17

3

9

2.5

5

2

7

1.5

1

1

4

0.5

3

0

2

-1

1

Total

49

4 of 18

Grouped Results

Score

Let’s call it

Count of Quickstarts

3.5 and 3

Pretty good

26

2.5 and 2

Average

12

1.5 and 1

Bad

5

0.5 and 0 and -1

Quite poor

6

Total

​

49

5 of 18

Graphed Results

6 of 18

The bottom eleven

Score 1.5

  • MapSlicer

Score 1

  • actinia
  • gvSIG Desktop
  • OpenCPN
  • zyGrib

Score 0.5

  • Geomajas
  • Mapnik
  • OpenStreetMap

Score 0

  • liblas
  • ncWMS

Score -1

  • GMT

7 of 18

Season of Docs

  • The writing period for Season of Docs runs from September through to end of November 2019.
  • Roughly 2.5 months remaining.
  • How shall I spend that time?

8 of 18

Suggestion for effort: Help the few

Try and get these guys over here

I work intensively with these projects to bring the ‘worst offenders’ up to a more acceptable level of quality.

9 of 18

Suggestion for effort: Help the many

Improve the template and work with projects to help everyone help themselves “step up”.

10 of 18

Help the few

  • Create detailed mark-up on the lower scoring quickstarts for specific issues
  • Reach out to contact person for each quickstart and work intensively with these projects to help them improve the guide

​

Questions

  • Return on investment - Do these lower-rated quickstarts have enough usage to justify improving them?
  • How hard will it be to improve them? Contactability of project members, time constraints, language barriers, etc
  • What do we gain? Consistency. Accuracy.

11 of 18

Help the many

  • Review the quickstart template and update if necessary.
  • Create tickets in trac for specific issues in each quickstart.
  • Update the 'How to document the Quickstart file' page.
  • Reach out to community and let them update the quickstart based on the template

Concerns

  • The quality gap widens - the good ones get better but the poor ones remain poor.

12 of 18

General observations

  • There are a lot of acronyms.
  • The quickstarts assume the audience is experienced with geospatial software.
  • None of the quickstarts talk about what the software could be used for. Perhaps this is covered somewhere else?
  • Some of the quickstarts have GUI workspace overviews, some don't. I think it’s better to link out to this information.
  • It would be good to add some kind of measure, like “Did you find this helpful?”.
  • It will be hard to make these consistent across the board due to the different nature of the software packages. We possibly need 3 or 4 different "template flavours" based on desktop, web, CLI, etc.
  • Templates work for structure but not language. We’ll need a style guide to set tone. Perhaps there is one already?

13 of 18

How did the others score?

14 of 18

Score 3.5

  • 52 North WPS
  • gdal
  • geoext
  • GeoNode
  • Leaflet
  • MapProxy
  • OpenJUMP GIS
  • OpenLayers
  • OTB
  • pgRouting
  • pycsw
  • QGIS Server
  • R for Spatial Data
  • Rasdaman
  • SAGA
  • SpatiaLite
  • uDig

15 of 18

Score 3.0

  • Cesium
  • deegree
  • EOxServer
  • GeoMoose
  • GeoNetwork
  • GpsPrune
  • GRASS GIS
  • PostGIS
  • QGIS

16 of 18

Score 2.5

  • 52 North SOS
  • GeoServer
  • iD editor
  • Mapbender
  • t-rex

17 of 18

Score 2.0

  • istSOS
  • JOSM
  • MapServer
  • mapcache
  • Marble
  • PyWPS
  • Zoo Project

18 of 18

The lowest scorers

Score 1.5

  • MapSlicer

Score 1

  • actinia
  • gvSIG Desktop
  • OpenCPN
  • zyGrib

Score 0.5

  • Geomajas
  • Mapnik
  • OpenStreetMap

Score 0

  • liblas
  • ncWMS

Score -1

  • GMT