If you have ever opened the help section of a GIS application and closed it again within thirty seconds, you are not alone. A lot of GIS documentation is technically accurate, written by people who clearly know the software, and almost completely unhelpful to the person trying to get a task done. That is not bad luck. It is the predictable outcome of how this kind of documentation usually gets produced.
Documentation tends to fail in quiet ways. Nobody complains loudly because nobody expects much from a help file. Users find a workaround, ask a colleague, or just stop trying. Support tickets pile up. The same questions get answered three times a week. Features sit unused. And somewhere in the project plan, “update the docs” stays permanently amber.
It is worth looking at why this happens, what good documentation actually looks like, and what changes for teams who decide to take it seriously.
Why most GIS docs are written for the wrong reader
The first problem is that documentation is usually written by the engineers who built the feature, under the same deadline that shipped the feature. Engineers are not bad writers by nature, but they are working with two big disadvantages. They know the system too well to see it the way a new user sees it, and they have no time to learn how to write for anyone else.
The result is a help page that explains what each button does, in the order the buttons appear on the screen, in the vocabulary of the people who designed it. That is a reference, and a reference has its place, but it is not what most users open the docs to find. Users come to documentation with a task in mind. They want to know how to do the thing they were asked to do. They are not browsing.
The second problem is that the audience for GIS software has changed, and a lot of documentation has not caught up. Twenty years ago, if you were using a GIS application, you were probably a cartographer or a geographer by training. Today, the people opening the same software are planners, environmental consultants, civil engineers, asset managers, surveyors, utility staff, and analysts in dozens of other fields. They need to produce a map or run an analysis to support a decision in their actual job, which is not GIS.
Writing the same documentation for both audiences is a recipe for satisfying neither.
What “accurate but unusable” actually looks like
You can spot the pattern in a few common signs. Sections are organised by menu, not by goal. The language assumes the reader already understands projections, topology, geoprocessing, and the rest of the vocabulary. Screenshots are missing or out of date. Examples use generic placeholder data that does not look like anything the reader actually works with. Cross-references send you in circles.
Crucially, the documentation almost never says what to do first. A new user opens the docs hoping to find something like “I have a shapefile of council boundaries and a CSV of population data. How do I join them and make a thematic map?” What they get instead is a section called “Working with Tabular Data,” which is technically the right place to start if you already know the answer.
It is accurate. It just does not help.
What good GIS documentation does differently
Good documentation starts from the reader’s situation, not the product’s structure. The change is harder than it sounds, because it means writing about the same software in a different shape entirely.
A few principles separate documentation people return to from documentation they avoid.
It is organised by task, not by menu. The top-level structure follows what the user is trying to do. “Make a thematic map,” “Join external data to a layer,” “Export a print-ready PDF.” The reference still exists, but it sits behind the tasks.
It assumes the reader is competent but not expert. The reader is intelligent. They know their own work. They do not, however, know that “spatial join” is the term you use for what they would call “matching the data up.” Good documentation either uses plain language or defines the term the first time it is needed.
It is layered. A reader who needs a quick answer gets one near the top. A reader who needs more detail can scroll. A reader who needs the full reference can click through. The same page works for a five-minute user and a fifty-minute one, without slowing either of them down.
It uses realistic examples. The sample data looks like data the reader might actually have. A planner reading documentation for a parcel analysis does not want to see “Layer A” and “Field 1.” They want to see something that resembles a parcel layer with a zoning attribute. Realistic examples cost more to produce. They are also the difference between a tutorial that lands and one that does not.
It says what to do when something goes wrong. Real users hit errors. Documentation that pretends errors do not happen is documentation that loses trust the first time they do. A short troubleshooting section, written from the user’s symptom and not the system’s log file, is one of the most valuable parts of any help system.
The cost of getting it wrong
It is tempting to treat documentation as a presentational matter — a thing that affects how the product feels rather than how it performs. That is a comfortable framing for teams under pressure, because it lets documentation slip down the priority list without anyone needing to defend the decision.
The cost shows up elsewhere. Support load is the obvious one. Every question that documentation could have answered becomes a ticket, an email, or a call. Multiply that by a year and you have a meaningful percentage of a support team’s time. Feature adoption is less visible but more expensive. A feature with poor documentation is, for most users, a feature that does not exist. The team that built it has nothing to show for the effort, and the next round of planning is harder to justify.
For commercial GIS products, there is also a churn cost that almost never gets attributed to documentation directly. Users who feel out of their depth do not always complain. Sometimes they just renew their licence somewhere else.
What a serious documentation effort looks like
Treating documentation seriously does not mean hiring an army of writers or stopping development to rewrite everything. It usually means three changes in how the work is planned.
The first is recognising documentation as a deliverable in its own right, with its own author, brief, and review. Not “the engineer writes it on Friday afternoon.” Someone whose job is to write it, and who has time to do so before the feature ships.
The second is involving real users in the review. That can be formal usability testing, or it can be as light-touch as asking a colleague from outside the engineering team to follow the instructions and note where they get stuck. The first review of any piece of documentation should not be by the person who built the feature.
The third is treating documentation as something that ages. A help page written a year ago for a version of the software that no longer exists is worse than no documentation at all, because it actively misleads. A small amount of regular maintenance, tied to releases, keeps the content trustworthy.
The short version
Documentation that works is documentation written for the reader rather than the system. It assumes the reader has a job to do and limited patience. It is organised around tasks, uses realistic examples, and is honest about where things can go wrong. It costs more to produce than the alternative, but it costs less than the alternative once you count the support tickets, the unused features, and the customers who quietly leave.
The good news for any team currently sitting on documentation they are not proud of: most of the improvement comes from a change in approach, not a change in budget. Start with the three or four tasks users actually do most often. Write those properly, with realistic data and a real review. Then keep going.
