Tag Archives: geography

Insights from mixing writers with open source

The OSGeo Foundation participated in Google’s first Season of Docs, where Google sponsored technical writers to contribute to open source projects. The Open Geospatial Foundation (OSGeo), is an umbrella organization for around 50 geospatial open source projects. I’ve contributed to a number of these projects over the years and co-mentored the two Season of Docs technical writers allocated to us.
Screenshot from the OSGeoLive distribution we've been documenting, available under a CC-By license.
During our involvement we discovered that, like many open source projects, we knew little about:
  • The state of our docs.
  • What we were aiming for.
  • What our priorities were.
  • The details of the challenges we faced.
  • How to improve.
We learned:
  • How hard it is to keep tech docs current.
  • Skillsets from multiple roles are needed to create good docs.
  • Open source’s docs and writing processes are immature when compared to software development.
It is an exciting problem space with high-value challenges ready to be tackled. It reminds me of the early days of open source before it became trendy with business.

What should tech writers work on?

Open source communities welcomed the chance to have tech writers improve our docs, and expressed a pressing need for it, but found it challenging to articulate what exactly needed fixing.
  • People explained that their project docs often hadn’t been updated between doc releases.
  • Some projects had noticed new features that had not been documented.
  • Other projects had issue lists—collating observed deficiencies—but had no systematic review.
  • Most observed that docs were created by developers with no formal tech writing training.
  • Many noted that docs written by non-native language speakers and would benefit from grammatical review.
But where should we start? We needed to decide on what we wanted, what we should work on first.

What’s the definition of good docs?

And then we realized that we didn’t have a good definition of “good documentation.” For our software projects, we have a comprehensive incubation process to assess the maturity of software and the project’s community, but we couldn’t find a similar set of metrics to define “good documentation.” So we started TheGoodDocsProject, to collate “best-practice templates and writing instructions for documenting open source software.” This helped us define what we were aiming for, and prioritize what we can achieve with our available resources.

Documentation audit

Once we knew what good docs looked like, we were then able to audit the status of project’s docs:
  • What documentation do we have?
  • Does it cover all the functionality?
  • Does it cover end-user needs?
  • Is the documentation any good?
We discovered that the quality, currency, and completeness of our OSGeo docs were immature when compared to the quality software they described.

It takes a village to raise good docs

In researching open source projects’ documentation needs, it’s become clear that crafting good docs requires multiple skillsets. Ideally, a doc team would have access to:
  • A developer with a deep understanding of the software being described.
  • A software user who’s able to explain the application within the context of the application’s domain.
  • An educator who understands the principles of learning.
  • An information architect who understands how to structure material.
  • A writer who writes clearly and concisely with good grammar.
  • A translator who can translate docs into multiple languages.
  • A DevOps person who can set up doc build pipelines.
  • A community builder, facilitator, and coordinator, who can inspire collective action, capture offers of help, and help all these different personas collaborate together.
Technical writers usually have a high-level understanding of most of these domains and their skills are often under-appreciated and under-utilized, especially if directed with a vague “just clean up the grammar and stuff”. The best docs typically have been influenced by multiple stakeholders, which can be partly achieved using templates to collaborate between domains, timeframes, projects and organizations.

Tools for documenting open source projects are painful

We experienced significant difficulties trying to convert between writing and software toolsets. We love the versioning of git, are frustrated by clunky Markdown interfaces, and want access to editing and review workflows of Word and Google docs, along with grammar and syntax plugin tools such as Grammarly. Translation tools such as Transifex are pretty cool, too.

If a project were to address this use case, it would be an awesome gift to the open source community. Having someone write an application which addresses this use case would be helpful. Maybe there is an idea in here for a future Google Summer of Code?

Achievements during OSGeo’s Season of Docs

We’re quite proud of our achievements during OSGeo’s participation in the Season of Docs. Our allocated tech writers have amplified the effectiveness of our existing documentation communities, and our documentation communities have amplified the effectiveness of these tech writers.
  • Felicity Brand worked with around 50 of OSGeo’s open source projects to update their Quickstarts as part of our OSGeoLive distribution of software.
  • Swapnil Ogale worked directly with GeoNetwork’s documentation team, auditing the breadth of docs, and their quality, setting up templates for future docs to work towards, and updating a number of the docs.
Further:
  • We kicked off TheGoodDocsProject—“Best practice templates and writing instructions for documenting open source software.”
  • In conjunction with the OGC and ISO spatial standards communities, we kicked off an OSGeo Lexicon project, to coordinate official definitions for terminology used within the OSGeo context. This will apply best practice definitions to prior haphazard glossaries.
  • We did a deep-dive analysis of the documentation challenges faced by QGIS, one of OSGeo’s most successful projects. Surprisingly, their biggest problem isn’t a lack of tech writers or complicated tools (although they are factors). The key problems center around:
    • Poorly capturing community goodwill and offers of assistance.
    • A lack of direction.
    • Struggling to keep up with a rapidly evolving software baseline.
    • Insufficient writing expertise.
    • A high technical barrier to entry.
    • Documentation and training being generated outside of the core project.
    • Awkward documentation tools and processes.

Season of Docs 2020

Does tech writing interest you? If so, check the Season of Docs projects for 2020 and consider taking part.

By Cameron Shorter, Google technical writer and geospatial open source developer

Announcing the S2 Library: Geometry on the Sphere

Google has always embraced new approaches to organizing all the world's information, and this includes all the world's geography. Today we are announcing the open source release of Google's S2 library, the core geometric library on which Google's global geographic database is built.

A unique feature of the S2 library is that unlike traditional geographic information systems, which represent data as flat two-dimensional projections (similar to an atlas), the S2 library represents all data on a three-dimensional sphere (similar to a globe). This makes it possible to build a worldwide geographic database with no seams or singularities, using a single coordinate system, and with low distortion everywhere compared to the true shape of the Earth. While the Earth is not quite spherical, it is much closer to being a sphere than it is to being flat!

Notable features of the library include:
  • Flexible support for spatial indexing, including the ability to approximate arbitrary regions as collections of discrete S2 cells. This feature makes it easy to build large distributed spatial indexes. (The image above illustrates the S2 space-filling curve, an important tool used for spatial indexing.)
  • Fast in-memory spatial indexing of collections of points, polylines, and polygons.
  • Robust constructive operations (such as intersection, union, and simplification) and boolean predicates (such as testing for containment).
  • Efficient query operations for finding nearby objects, measuring distances, computing centroids, etc.
  • A flexible and robust implementation of snap rounding (a geometric technique that allows operations to be implemented 100% robustly while using small and fast coordinate representations).
  • A collection of efficient yet exact mathematical predicates for testing relationships among geometric primitives.
  • Extensive testing on Google's vast collection of geographic data.
  • Flexible Apache 2.0 license.
The reference implementation of the S2 library is written in C++, and subsets have been ported to Go, Java, and Python. An early version of the code was released in 2011, but today's announcement represents a major update along with a commitment to maintain the library going forward. The code is under active development and new features will be released regularly. (The Java port is based on the 2011 code and does not have the same robustness, performance, or features as the current C++ version.)

Our C++ code repository is here: https://github.com/google/s2geometry
And check out our documentation here: https://s2geometry.io

To learn more, start by reading the overview and quick start documents, then explore the documentation site. The library also has extensive documentation in the header files, which is where the most authoritative information can be found. More introductions and tutorials will be added over time - contributions are welcome!

The S2 library was written primarily by Eric Veach. Other significant contributors include Jesse Rosenstock, Eric Engle (Java port lead), Robert Snedegar (Go port lead), Julien Basch, and Tom Manshreck.

By Eric Veach, Software Engineer