If you write documentation for GIS software, the audience you grew up writing for is no longer the only audience reading. The professional cartographer with formal training is still in there somewhere — but they are now sharing the help pages, the tutorials, and the in-product tooltips with planners, environmental consultants, surveyors, engineers, asset managers, field crews, and, in growing numbers, members of the public who arrive at a web map and start clicking.
This is not a complaint. The democratisation of geospatial tools is one of the better things to happen to the industry. But documentation has often failed to keep up, and the gap shows. The words on the page assume a level of background that the reader does not have. The interface mentions concepts that were never explained. Help articles answer questions that nobody outside the field would think to ask, and quietly ignore the questions they would.
Writing for this new audience is not about dumbing things down. It is about meeting the reader where they actually are.
The audience has changed more than the docs have
The shift has been gradual, which makes it easy to miss. Twenty years ago, GIS software was specialist software. The people opening it had usually studied geography or cartography, knew what projections and coordinate systems meant before they ever touched the tool, and could be expected to navigate menus organised around those concepts.
Today, the user base looks different. A council planner uses GIS to check flood zones against a planning application. A field engineer uses GIS on a tablet to capture asset locations. A utility operator uses GIS to plan a maintenance run. An environmental consultant uses GIS to produce a habitat map. None of them think of themselves as a GIS user, primarily. They think of themselves as a planner, an engineer, an operator, a consultant — using a GIS tool to do their actual job.
The vocabulary they bring with them is the vocabulary of their job, not the vocabulary of cartography. They might know exactly what a planning permission is and have no idea what a topology rule is. They might know precisely how to read a soil report and have no idea what raster reclassification means. The mismatch between their vocabulary and the documentation’s vocabulary is, quietly, the biggest barrier to them being good at the software.
The vocabulary problem
Geospatial work has accumulated decades of specialist terminology. Some of it is genuinely necessary — you cannot meaningfully work with spatial data without understanding coordinate systems, for example. Some of it is the legacy of an academic field that did not need to explain itself to outsiders. Documentation tends to treat all of this terminology equally, which is a mistake.
There are three rough categories worth distinguishing.
Concepts the reader needs to understand to do their job. Coordinate systems and projections fall here. So does the difference between vector and raster data. If a planner is going to overlay datasets meaningfully, they need a working understanding of projections. The documentation has to teach this, not assume it.
Concepts the reader can use the product without understanding fully. Topology rules, geodesic versus planar measurements, the details of geometry storage. These matter at depth, but a casual user does not need to know them to load a layer and run a buffer. Documentation that opens with these concepts pushes new users away unnecessarily.
Concepts that are pure jargon — internal terms that exist because of how the software was built. “Mxd,” “geodatabase classes,” “data frame,” “definition query.” These are real things, but the reader has no obligation to learn the term to do their work. Documentation that uses internal terminology before defining it has chosen the engineer’s convenience over the reader’s.
A good rule: the first time a domain term appears, define it in a sentence. The first time an internal term appears, ask whether it needs to appear at all.
Mental models, not feature lists
The deeper challenge is not vocabulary but mental models. An experienced GIS user holds a model of the software in their head that helps them predict where things live and what each operation will do. New users do not have that model yet, and a feature-by-feature reference does not build it.
The most useful early documentation is the documentation that builds the mental model. Not “here are all the tools in the analysis toolbar,” but “here is how analysis fits into a typical workflow, and here is the order in which you will use these tools.” Not “here is the layer panel,” but “here is what a layer actually is, and why your data is loaded into layers rather than into one big map.”
This is the kind of content that experts find unnecessary, because they have built the mental model years ago. They sometimes object to its inclusion on the grounds that it bloats the docs. But the experts are not the audience the docs are losing. The losing audience is the planner who closed the help file three minutes in because none of it made sense.
Task framing, not feature framing
The other shift is from organising documentation around features to organising it around tasks. Feature-organised documentation answers the question “what does this button do?” Task-organised documentation answers the question “how do I do the thing I need to do?”
For a non-expert user, the second question is the only one they are asking. They do not know which button to look at. They do not know which menu the tool lives under. They know what they are trying to accomplish in their work. Documentation that meets them at the level of their goal — and only then introduces the features needed to accomplish it — is documentation they can actually use.
This sounds obvious. It is also rare. Most software documentation, including GIS documentation, is still structured around the product’s anatomy: menu by menu, panel by panel, tool by tool. Restructuring around tasks is a substantial undertaking, but it changes everything about how the docs perform.
What “meeting them where they are” looks like in practice
A few habits separate documentation that lands from documentation that does not, when the reader is not a geospatial specialist.
Examples use realistic data. Not “Layer1” and “Field2.” A planning example uses a planning application layer with realistic attributes. An environmental example uses a habitat dataset. The cost of producing realistic sample data is significant; the value of using it is far higher.
Screenshots show the whole task, not just the dialog. A close-up of the projection dialog is unhelpful if the reader does not know which menu it came from. A wider screenshot showing the menu path and the dialog together gives the reader something to compare their own screen to.
Outcomes are described, not just steps. “Click Run.” Then what? “Click Run. The tool will create a new layer containing the selected features. The new layer will appear in your layer panel above the original layer. You can rename it by right-clicking on it.” The reader is now equipped to verify that they have done the thing correctly, instead of trusting that they have.
There is a glossary, and it is honest. A focused list of terms a new user will encounter in the first few sessions, with explanations written for a non-specialist.
The docs admit when something is complicated. If a concept is genuinely difficult, the docs say so. That kind of honesty does more for reader confidence than any amount of cheerful framing.
The thing that does not need to change
It is worth saying clearly: writing for a less-expert audience does not mean producing less rigorous documentation. The depth and the accuracy are still required. The reference still needs to be complete. The technical content still needs to be correct.
What changes is the path the reader takes through the material. The non-expert enters through task-led content with concrete examples and plain language. The specialist still has the reference they need, accessible through the same documentation, organised in a way that respects their time. Both readers are served, by the same body of documentation, because the structure allows each to find what they came for.
The short version
The GIS audience has grown wider, and documentation has lagged behind it. The reader you used to write for is still in there — but most readers are now non-specialists using a GIS tool to do work in another field entirely. Meeting them where they are means rethinking vocabulary, building mental models before listing features, organising around tasks, and treating the new audience as competent professionals who happen not to be experts in your tool. The reward for doing this work properly is documentation that actually helps people use the software they paid for.
