It would be an understatement to say that the geospatial industry is complicated. It's full of terms and theoretical aspects that can be a barrier for an outsider to the industry. As technical writers, our main goal is to explain things in a clear way, so that even a beginner feels empowered to explore this beautiful world of geospatial data and the opportunities it presents.
Here’s what you'll learn about in this post:
- The global English principles and why it’s important to follow them
- Why it’s important to be concise when writing technical documents
- How we dealt with terminology confusion brought on by STAC
Global English principles at work
To adhere to global English principles means to write accessible documentation that’s comprehensible to a diverse audience. This can mean non-native English speakers or people unfamiliar with the industry.
Compare these examples:
| Example #1 | Example #2 |
|---|---|
| A workflow is a directed acyclic graph of data and processing blocks. The workflow defines the order in which each operation associated with a certain block is performed. A workflow always starts with a data block and may subsequently be followed by one or more processing blocks. | A workflow is a sequence of data blocks and processing blocks. It defines an order for operations. A workflow starts with a data block, which may be followed by processing blocks. |
It might be nice to know a workflow is a directed acyclic graph, but does it help with understanding? When the goal is to onboard a user quickly, then it will only slow them down. Moreover, complicated terminology and the use of heavier terms can feel arrogant. A well-known example of this is “utilize” vs. “use”.
Here are several global English principles that we follow in our documentation:
- We use simple sentence structures.
- We use simple words and try to avoid ambiguity and jargon. Those complex terms that can't be avoided, are defined—for example, imaging modes vs. acquisition modes or DSMs vs. DTMs.
- We maintain consistency in language, terminology, style, and formatting.
Key takeaway: Following global English principles expands the audience base and makes the documentation more accessible.
The importance of conciseness
It's nice to have additional information, but the creation of a clear step-by-step tutorial shouldn’t be compromised by an excess of supporting details; conciseness is always more important. When a lot of side-topic information gets added, it's not only the text that gets watered down but also the reader's attention. Think of it this way: a reader starts with a 100% attention span that declines every second. You have very little time to catch their attention with a promise that the article they're reading will help them solve their issues or answer their questions.
Compare these examples:
Example #1
Example #2
This is the same article before and after refactoring. It’s not an easy topic, but see how example #2 is much more straightforward: from the start, you know that the entire instruction consists of 5 steps. This makes a complicated topic like custom block development less scary. For comparison, in example #1, the headings on the table of contents on the right are long and complicated. The reader will need to look 2–3 times to understand the structure of this article.
What to do with additional information? Create a separate section for it. An example from our Documentation hub would be the Reference section. When documenting different types of collections from different providers, we faced an interesting question: how do we explain all of this and allow our customers to compare the offerings, considering collections might be drastically different? They might have different types of accepted inputs or provide the resulting imagery differently. To keep collection articles straightforward and concise, we moved additional information to the reference section, and provided links to it where relevant, like this:
| Specification | Description |
|---|---|
| Acquisition mode | Mono Single Pass Stereo Tri-Multi Pass Stereo |
This is an example from KOMPSAT-3. We used provider terms so that people already familiar with KOMPSAT's product specifications can understand exactly what’s on offer. For the rest of the readers, we provided a link to the reference article to explain that Single Pass Stereo and Tri-Multi Pass Stereo can be mapped to the stereo acquisition mode.
Key takeaway: Write concisely. Not everyone needs additional information, but make sure that those who need it, can find it.
A tale of confusing terminology
The importance of having consistent terminology can't be overestimated. When a term is used with several meanings or several terms are used to mean the same thing, it affects the clarity of your docs and—more importantly—product adoption, because a user can get misled.
We were very excited to start planning documentation for the STAC release, until one thing came to light: overlapping terminology. It sure seemed like STAC had used every major term we were already using on the platform to mean something else:
| Term | Our platform | STAC |
|---|---|---|
| Catalog | A source of archive data | A top-level object for navigating STAC |
| Collection | Geospatial datasets | Order results |
| Asset | Order results delivered to storage | A geospatial feature of a STAC item—for example, one band |
The issue was that STAC is a community specification, and in order to be STAC-compliant, we had to use its terms. But platform terms were also carved in stone in some way—the terms “catalog”, “collection”, and “asset” have long been used in our public communication. A simple change in the documentation wouldn't change the fact that already established endpoints used URLs with /catalog, /collections, and /assets.
Here's how we solved the issue:
- We introduced an extensive dictionary for STAC objects.
- We drew a diagram to visually map STAC and UP42 objects.
- We made sure to use STAC-related terms with a “STAC” prefix—for example, STAC catalog.
- We made sure to use platform terms with their respective qualifiers when they are used alongside STAC terms—for instance, “geospatial collections” or “UP42 assets”.
Key takeaway: Always ensure the terms you're going to use for your products don't overlap with existing industry terms that have another meaning.
In conclusion
The geospatial industry's complexity can be overwhelming, but through a commitment to clarity and simplicity in our documentation, we aspire to invite newcomers into the realm of geospatial opportunities. By adhering to global English principles, embracing conciseness, and untangling confusing terminology, we pave the way for a smoother journey into the world of geospatial data. As you begin your exploration, we invite you to visit our Documentation hub.
