Launching a New, More Intuitive FaunaDB Docs Structure
Happy Tuesday! Well, at least it's happy around here. I'm very excited to reveal, at long last, my final project as a technical writer at Fauna (I've since moved on to Product): a brand new organization of our documentation! I hope you enjoy it as much as I enjoyed creating it, and please check back frequently as our brand-new technical writer will be updating pages and adding content soon. If you're curious about the how and why of this update, I wrote all about it below.
Coming to Fauna early last year, I was impressed by both the quantity and quality of docs that had been created without a dedicated technical writer. It's really easy to treat documentation as an afterthought, especially while in the thick of development and growth. It said a lot about my coworkers' passion for FaunaDB that they cared enough to write about it. But even with the existing docs, we were still in the very beginnings of documentation efforts, which is a very exciting place to be.
It was immediately apparent that I was facing a unique opportunity to really plan a future-oriented information architecture (IA) that we could use to guide our docs through the growth and change that all startups face. I won't say that is every tech writer's dream, but I think many would relish the opportunity to right the observed wrongs of the past. Of course, that's no small amount of responsibility and challenge. So I decided to build on defendable foundational principles: content categories and content types.
In the world of software, there are some high-level, general content categories that apply across the board regardless of what your software is or who's using it:
- Product: Any content that is meant to explain or present the workings, architecture, and operations of or integrations with the software. Generally, these docs will be consistently maintained and users will revisit them as needed.
- Marketing: Any content specifically meant to entice, persuade, or tell a story about the software or company. Generally, these docs will have an expiration date and be removed, updated, or entirely rewritten as new campaigns replace the old ones.
- Training: Any content that is a full start-to-finish walkthrough of interrelated tasks designed to help a user achieve an outcome, such as "Creating a trading app with our software". Generally, these docs are meant to be used once, and often have a path from one to another to build skills.
Within the Product Docs category, there are several types of content:
- Task: Content that answers the question, "How do I do X?" and is a means of guiding users through the steps of accomplishing a single task using the software.
- Reference: Content that presents a complete list of specifications for a given thing (APIs, configurations, etc.).
- Overview: Content that introduces a feature or aspect of the software at a high level, answering the questions, "What is this?" and "How does it help me?"
- Theory: Content that describes how something was architected and the logic behind why X was chosen over Y; this content is meant to assist users in understanding the underlying assumptions and principles guiding the software.
Using these categories and types along with user personas, we are able to ask of each individual doc:
- What user is the doc targeted at?
- What is this doc doing for the user?
But how does any of this have anything to do with information architecture (IA)? A really good IA operates along two axes: side navigation (navigational IA) and the path a user will take through the docs at various points of experience (path IA). If you just consider navigational IA, you can end up developing a Dewey Decimal-like IA which requires any given user to know exactly what they want and what they are looking for. If you just consider user paths, you can develop an overly prescriptive IA that is annoying for users who just want the answer to a specific question. You also want to keep an eye on your product roadmap, because you want room in your IA to expand and address new things being built. The IA should balance the needs of the content you currently have and the content that you want to create for both existing and new features.
With all of this in mind, we decided to implement an IA organized by high-level actions, which would let us have broad sections that could grow to accommodate an ever-expanding feature set, while simultaneously allowing for both a prescriptive path and a low-friction navigation for those looking for a specific thing. To hone our approach, we developed three separate options and user-tested them internally, iterating on the winner until we had a plan.
Before we get into what you can currently see on the docs site, let me take just a moment to go through the plan we chose and are implementing. We have top-level headings that are the first thing you see in the side navigation when you visit our docs site. These are:
- Introduction to
- How to
- Drivers and Tools
Each of these have subheadings which, for the moment, will populate above the main side nav when you click on a top-level heading. Each individual page, including the subheading index pages, will have in-page directions to follow up with additional pages, allowing you to choose the best path for your needs. Topics under each heading, for instance “How to,” are organized weighing difficulty and user interest.
You'll notice that we don't currently have every section available on our side navigation, and that is because we have a LOT of docs to write this year. But we hope you'll find the new docs IA more intuitive and easy to navigate, especially as we continually add more documentation. Let us know what you think! Have feedback or requests? You can reach us at firstname.lastname@example.org.
If you enjoyed this topic and want to work on systems and challenges just like this, Fauna is hiring!