February 2019 I began a new job with an enterprise data-analytics software startup that was about four years old, called Incorta. When I started, their existing content was, as is typical, scattered and messy.
My goal: Fix it. Make the documentation awesome, innovative, and an integral part of the strategic direction of product and user experience.
The previous writer was a junior engineer-turned-writer who did an amazing job creating a solid foundation of content. But, as often happens, he was given multiple tools, instructions, and inputs. And the product documentation turned into a scattered mess of not-always-updated-or-accurate content written by many people and saved in many locations. Internal stakeholders couldn’t find the latest content, not to mention the users. Employees in customer-centric roles sent frantic emails trying to find the latest version of “official” documentation or wrote their own to send to customers.
Startups often assume they need a technical writer to come in and just update the documentation. Maybe they expect the writer to suggest a better tool. Depending on the product, the users, the stage the product is in, and how much content already exists, this might not be enough.
Incorta was smart enough to know they needed someone who could fix the docs, present the information better, and create consistency between the language in the product and the product documentation. They knew they needed an effective documentation topology, content development plan and workflow, and an approach to unify existing content. They needed a content strategist. Incorta prizes innovation and promised the freedom to implement these as I saw fit. I jumped at the opportunity.
The easy, but lower quality user experience option: Update the PDFs written in InDesign, Google Docs, Zendesk, and the existing community forum (some of the tools they already used to create and deliver content). I could have left things as they were and updated what was there where it already lived. Since four or more locations for content are confusing for users, the user experience would have made us look disorganized to existing and potential customers. Not awesome. Not innovative. Not strategic. And, possibly gives the impression that we didn’t know what we were doing. And, if we don’t look like we know what we’re doing with product documentation, what other doubts might prospects have about the quality of the product itself?
The harder, but better user experience option: Pick one of our existing tools, migrate other content to that tool, and update from there. Most of the existing options, though, were limited in their capacity to support the large body of existing content and the product growth trajectory.
The biggest challenge and best user experience option: Consolidate content in one new location with an appropriate tool and migrate all content to that tool. This is a harder path and a harder sell. But this is what it would take to reach the goal. Choosing a new tool, then converting all content from four or more locations written by product managers, engineers, customer success, support, customers(!), and an overloaded part-time writer, is a lot.
Chasing down all the latest content alone is quite the challenge alone, but I’d also have to shut down new content creation by people outside the writing team (meaning a potential gap in updated content) and convince them to stop using some existing tools. I also had to create a new process for creating and updating content and educate many groups on why all this work is required for product documentation. Focusing attention on setting up tools, processes, and converting content, meant I couldn’t learn about the Incorta product. This was a risk I had to take to create a solid foundation on which to build content. I had to get input from others on how to organize information until I could learn the Incorta product and user journey. I’d also have to get product users and internal stakeholders used to finding content in the new location.
Fortunately, I like a good challenge.
Once I knew the challenge, the next step was to figure out what tool to use. In any company, considerations for product documentation creation and delivery tools include:
- How much content there is and how much there will be in the future. Incorta is enterprise software with multiple concurrent releases. The way we present information for this kind of product is very different from the way we present information for consumer software. User expectations are different, too.
- How we can optimize writing — write once and avoid maintaining several versions of the same content in different places? At a startup, lean content development is the only option.
- What format we will use to display content (PDF, desktop, mobile, in-app, etc.).
- How often we will need to update content and how many versions or release we will support.
- Other considerations. For example, will we want to localize? Will we want to customize the way we display content or convert it to another tool as we scale? Will we have or want non-technical writer contributors in the future?
In Incorta’s case, we needed 21st century content to support an innovative tool that is a fast, modern update to an old, slow industry. Cutting edge delivery on the web was a must-have first step. A doc website enables users to find content one location, scales easily, creates a low barrier of entry to localization, and allows for iterative updates to multiple concurrent releases. It’s also an expected delivery mechanism for enterprise software. In addition, as a data analytics company, we can get real information on how our content is being used, so the documentation can be data-driven to best serve our users. Bonus: data-driven content can inform the direction of product by helping identify pain points and missing features.
This narrowed our tool choices. PDFs were out (although they can be generated easily from most online tools, if needed). Article-based tools (like KBs in Zendesk) were also out because of the sheer scale of content and concurrent releases. We’d eventually have to migrate content out of this kind of tool if we used it, so better to avoid that pain upfront and start as we mean to go on.
DITA XML was an option, but provided no option for future contributors outside of technical writers, and is expensive to implement.
So, we chose to write our content in markdown. We store our code in Github and publish through a Jenkins pipeline to render the content using a tool called Gatsby, finally hosting it on our own site: docs.incorta.com.
This took some development work, thinking about how to set back end structures up for future scale and localization, and conversion of a lot of content. But, in three months, the new docs site was up and running and immediately available for writers to create and update content in seconds. And, now, we are data-driven, awesome, innovative, and contributing to the strategic direction of the product and user experience.