Our team creates documentation for ArcGIS Maps SDKs for Native Apps. Developers use our product to add mapping and spatial analysis to their apps. It includes SDKs for Kotlin, .NET, Qt, Swift, Java, and Flutter (beta), and supports deployment on several mobile and desktop platforms. In this article, I’ll provide some background on our documentation processes. I’ll also describe some of the work we’ve done to try to deliver better documentation more efficiently.
As our product documentation evolves, we strive to continuously introduce improvements in some key areas:
- Documentation by developers, for developers: Using tools and processes that manage documentation content the same way our development team manages their code.
- Eating our own dog food: Evaluating the documentation from a developer’s perspective and working to make it more useful.
- Feedback is a gift: Being agile to quickly provide updates to the live documentation.
Documentation by developers, for developers
How do you document a product created by and for developers? We started by making the doc creation tools and processes feel like those developers use. Most of the product information resides in the heads of the developers who create the product. We therefore wanted a system with tools and processes familiar to developers and software engineers.
Learning from our mistakes
In addition to the teams working on each SDK, new product features are developed by small teams of developers. Early on, we realized that a few writers synthesizing information from more than a dozen development teams was not scalable. Our original processes for getting content from subject matter experts were not well-defined. This resulted in updates from several sources (email, messaging, verbal communication), often without a publicly visible history or context. Additionally, doc authors often worked in silos according to the API or features they supported. Since resources available for each API differed, so did the quality of the documentation. We also relied on proprietary tools, with only a few licensed users able to directly work with the content. Internal previews of the documentation also became a bottleneck. Only a few users were able to publish a preview, and all work in progress was published to the same site. As a result, the doc team became gatekeepers for the content but still relied on subject matter experts for information. In our system, there was a stark disconnect between the technical experts and the content creation. The lack of familiar tools and procedures for previewing and reviewing updates made it frustrating for those outside the doc team to contribute content. For doc team members, the inability to efficiently share content across APIs and to quickly provide website previews created a lot of duplicated effort and a slow, error-prone review process.
A more open and accessible system
Our updated approach uses open-source tools that are readily available for anyone who wants to contribute to the documentation. Our developer experience team extends this framework with a set of custom tools. These include utilities for validating content and custom website components for displaying things like code blocks, notes, or expandable sections.
Here’s a summary of the tools we now use to maintain and publish our product documentation website:
- Gatsby: A React-based open-source framework that creates HTML pages from content stored in an extended Markdown format (.mdx). This static site generation approach was a fundamental break from our previous database-driven content management system.
- Custom React components: Components for rendering page elements like code blocks, demo apps, tables, and videos. These have been developed internally by our developer experience team and integrated into the Gatsby build system. Such components help simplify authoring by encouraging modularity, reusability, and clear abstractions.
- Visual Studio Code: Content for our website is authored in MDX format (.mdx), an extension to Markdown that lets you include JSX. We author documentation content using VS Code and use the MDX Visual Studio Code extension to provide language support for MDX.
- GitHub: All code and content needed to generate our website is maintained in our GitHub Enterprise repositories. Edits to the website are handled using familiar GitHub workflows.
- Jenkins: We use the open-source automation server for building our production website as well as an unlimited number of on-demand internal preview sites for testing.
Many of these tools, such as GitHub (for managing content) and Jenkins (for automating processes), were already used by the developers who create ArcGIS Maps SDKs for Native Apps. These tools improve our means of gathering information from experts, sharing content, and streamlining the review process. Documentation content is now stored in a GitHub repo alongside the code for the product and uses familiar processes for issue tracking and content management. Like the product, automated jobs build the documentation several times daily to ensure there aren’t errors. The documentation processes and tools are now much more aligned with those used by the product developers.
These changes have reduced headwinds for subject matter experts’ contributions, freed the doc team from being the gatekeepers (and bottleneck) for creating documentation, and brought documentation processes more in line with product development processes.
Eating our own dog (doc?) food
As Native Maps SDKs continue to add and enhance functionality, we strive to improve the overall quality of the documentation. These higher-level updates include things like adding new guide topics, reorganizing the presentation of content, and improving information discoverability. With each release, we document new features by first writing code to try them out. This helps us get a developer’s perspective on the new API, provides code snippets to illustrate the use of the API, and often directs the approach we take with the documentation. If we run into gotchas or points of confusion that other users may experience, we want to call those out to reduce frustration. While this hands-on approach helps, it doesn’t always capture the perspective of someone new to our SDKs (or perhaps new to geospatial technology). Most of us on the team are seasoned ArcGIS users who have worked with our product for some time. It’s often hard to take an objective, high-level look at our doc from a new user’s perspective … until a new author or intern joins the team.
Getting a fresh perspective
Even if they’re new to GIS, it doesn’t take long before a fresh doc author is down in the weeds with us. Before that happens, we do our best to capture their feedback from a noob perspective as they onboard with us. We give them some basic GIS requirements and ask them to implement an app using a Native Maps SDK of their choice. To complete the app, they can refer only to the following publicly available sources of documentation: developer guide, tutorials, toolkit, API reference, and samples. If they get stuck, they can use Esri community to look for help, but shouldn’t ask the team (or anyone at Esri).
Upon completing the assignment, they spend some time describing their experience. They let us know what resources they found most helpful, and where they were frustrated and offer suggestions for improvement. The fresh perspective we gain from these exercises is enlightening and helpful. We implement many straightforward suggestions where we can, while many others simply give us more to think about. Some common frustrations for experienced developers who are not familiar with ArcGIS are difficulty understanding some common GIS terms; confusion with the use cases for query, selection, or identify (when to use each); how to set the visible map area; difficulty navigating between help resources (conceptual doc, API reference, and samples, for example); and a poor documentation search experience.
Feedback is a gift
It’s frustrating to find an obvious mistake on our documentation website and not be able to correct it immediately. Maybe it’s a sentence that’s been repeated, a broken link that lots of users will click, a blatant misspelling, or a grammatical error. We used to have to wait up to one week before we could get such fixes onto the production website. What if a friend told you that you had some of the pizza you had for lunch hanging off your chin, but you had to wait a week to wipe it off? That’s what waiting to fix an embarrassing blemish on the doc site often felt like.
While we still take our time to implement larger updates (like creating a new topic), we try to address smaller fixes as soon as we can. User-reported errors and suggestions are especially important to us and are prioritized as they come in. With our current tooling, we can push updates to the live website twice a day if needed, meaning the longest we’d have to wait to make an update is less than a day unless it’s over the weekend. (As fast as that is for a doc fix, I’d still recommend wiping pizza from your chin as soon as you’re notified).
We spend a lot of time looking over new content before it goes live on our website. Once it’s there, we’ll likely read through it several more times without seeing any problems. That doesn’t mean that issues aren’t there, only that we don’t see them. That’s why we appreciate it when our users provide feedback and suggestions for the documentation. It may be a simple glitch like a misspelled word, a grammatical error, a broken link, or something more fundamental like contradictory or confusing information. We are always grateful when someone takes the time to point out such problems for us.
Most pages in our developer guide have a feedback widget so the user can let us know whether or not the current page is helpful by simply clicking a thumbs-up or thumbs-down icon. After clicking, we encourage the user to pass along additional details.
This feedback is routed into a centralized system monitored by several members of the documentation team (and other stakeholders). If the submitter includes an email address, we’ll follow up as soon as possible to offer help where we can or at least to say “thanks” for the feedback. If a fix is needed to address the feedback, we’ll immediately create a new issue in our documentation repository and prioritize it as a user-submitted bug.
Summary
The ArcGIS Maps SDKs for Native Apps documentation team works to improve the quality of our content by collaborating with the experts who create the product, working on the documentation from a developer’s perspective, and responding to our user’s needs. I hope this article helped provide additional context about our approach to our documentation and the areas we strive to improve.
Feel free to reach out if you’d like more information about how we create our documentation. I’d also love to hear from you if you’d like to discuss different documentation strategies or share suggestions and insights from your experiences. If you’re a student and interested in an internship with our team, check out the student programs at Esri.
About the author
