Last week, we relaunched Inedo Docs, the documentation portal for our products and related tools. Although the content is identical, it’s powered by a proprietary CMS we built from scratch. As a result, the articles load much faster, they’re easier to search, and everything is editable on GitHub.

In this article, I’ll talk about why we care so much about documentation, our rationale for building a proprietary CMS from scratch, and what this means for our users.

Why do we care so much about documentation?

We invest a lot of time in creating great documentation. It’s a lot of work, and it’s a whole lot more involved than simply writing some articles. In fact, it’s an integral part to building our software products.

For example, if we can’t think of how we will clearly explain what a feature does — and why you should use it — then there’s no sense in creating that feature.

Great Documentation is an All-hands Effort

Great documentation isn’t something you can simply delegate to a great technical writing team. In fact, some of the worst documentation you will ever read is created by technical writers – they don’t know the product very well, and no else wants to be involved in the documentation process.

Instead, the secret to great documentation is to have all teams that are involved with the product also be involved with documentation. This means technical writers do more than “just writing” – sometimes they help make the product easier to write about. And engineers need to be involved every step of the way.

The “all-hands” formula especially applies to sales and marketing. It’s their job to communicate the value of the products, and they need to speak in meaningful technical terms that the end-user will understand.

These value propositions need to directly tie to product features and use cases. They articulate why you should consider using a feature. “Alex thinks it’s a best practice” doesn’t take us very far.

Great Documentation is Great for Business

Although our all-hands approach is a lot more work than simply hiring technical writers to do it all, I think it’s worth the investment.

From a business perspective, great documentation sets us apart from our competitors. But more importantly, it also means that users can get the help they need right away by simply searching. This translates to significantly reduced support costs while keeping our customers happy and renewing.

It’s taken me many years to understand this, but it’s now become a core value at Inedo.

Although I’ll often hear from users that our documentation is great, I’m still not satisfied. I’m working on making it better, and I think our new, proprietary documentation system is a great improvement.

Building and Migrating from “nCMS”

For much of Inedo’s history, our documentation was a “subfolder” on inedo.com and was managed like most other web pages. That made sense in the beginning, since inedo.com was just simple website with a few pages.

Over the years, this simple website evolved into to a nightmarish Content Management System with hundreds of pages including documentation and blog articles. I affectionately named it “nCMS”.

nCMS was “kind of” intuitive in that content was mostly .md or .htm files, and mostly in directories that mapped to URL paths. But there were a lot of quirks and oddities, especially when it came to metadata, header formats, and those sorts of things.

Time to Move On

The main issue with nCMS is that it was painful for non-engineers to edit. nCMS required learning Git, Markdown, and approval workflows they weren’t used to. When things went wrong, it required engineer intervention and became “yet another product” for us to maintain.

Fortunately, there were plenty of capable website, blog, and documentation tools out there, and we selected and implemented different tools for different content types. The website and blog were easy, and we implemented marketing-preferred tools like Hubspot and WordPress.

But documentation required a different approach; we needed a “public knowledge management platform”. Something like a wiki, but that’s less wiki-like and more suited for public viewing and private editing.

We evaluated a number of solutions, and eventually decided on a SaaS product that both engineering and marketing teams would be able to use. And since it was SaaS, it was one thing less for us to worry about. Or so we thought.

Documentation is too Important to SaaS

Moving to our SaaS-based platform was a big effort, as it involved hundreds of articles and many more redirects. It took longer than expected, and once it all said and done… I had a major case of buyer’s remorse.

The hosted platform still required extensive training for non-technical members. While there weren’t nearly as many quirks as nCMS, there was a lot of nonintuitive behavior. Especially when it came to content review, redirects, and navigation.

But we stuck it out. It had a much lower maintenance cost than nCMS. Plus, as a SaaS, it would certainly get better… right?

Spoiler alert: it got worse. Much, much worse.

Complete Pain in the SaaS

SaaS products tend to be more feature-focused than customer-focused. The platform we chose was no exception, and they focused on acquiring new customers and growth instead of servicing their existing customers.

Why wouldn’t they? Their knew existing customers were “locked in” and that migrating to a new platform was more trouble than it was worth.

Throughout the years, we were treated to unwanted new features that would often break the administrative interface or have a negative impact on the end-user experience. This was a constant disruption, as the changes would “just appear” and break things. We had absolutely no control over their changes and were at the mercy of support to prioritize our problems.

We Picked the Best of the Worst

I wanted to blame the vendor, but this was my selection; I picked them from of a list of options we evaluated. Maybe I picked the wrong vendor, and we should switch?

Earlier this year, I reevaluated our shortlist again to see how much greener the grass was on their side. Somehow, even in retrospect, it seems I picked the “correct” choice?

Our fourth choice went out of business. The third got acquired and merged into a helpdesk tool. And our number two choice? They pivoted to “API Documentation” after burning through their first pile of VC investment.

For something as important as documentation, we can’t rely on someone’s hosting. Especially in such an unstable field like public knowledge management, where nothing is standardized and we can’t easily move to a new provider.

Searching for Self-Managed Docs

With hosted documentation off the table, we needed to find a self-hosted documentation solution.

Just about every option was free and open source, but none of them worked out of the box. At the very least, we’d need to do some styling – but the bigger issue was importing hundreds of articles and making sure the old URLs at least redirected to the new.

These self-managed platforms also had a steep learning curve like nCMS. Although they worked with files and folders that mostly mapped to URL paths, there were all those nonintuitive quirks when it came to metadata, navigation trees, etc. And also like nCMS, they would be painful to edit because they required a local server, Git knowledge, etc.

Creating a Proprietary CMS… Again

I wasn’t satisfied with any of the self-hosted documentation management systems. I knew we could build something that perfectly fit our requirements, but it didn’t seem wise to maintain “yet another product”. And then I thought about it some more.

Serving a bunch of files from disk isn’t exactly a hard problem to solve. Our own system would also give us full control, which means we could consider two key requirements: import hundreds of existing articles and be “usable enough” for nontechnical members.

Building Engineering-driven Documentation

As an engineer-driven company, we wanted our documentation to be engineering-driven as well. This means:

• Git-based Content; all articles and related content (images, etc.) should be in a Git repository and follow standard Git practices like clean commits, branching, etc.
• CI/CD Process; content changes are created locally, committed to Git, built to a test server, and then deployed to production
• Pull-request Approval Process; when changes need to be reviewed for any number of reasons, use a feature branch that gets deployed to a test server and pull-requests
• Simple to edit content; just navigate to the corresponding file, make a change, commit, and then deploy

We also needed the system to be “usable enough” for nontechnical users. This was a bit of a challenge, as their preference would be a WYSIWYG-based editor in an admin portal similar to WordPress. Instead, we created:

• Basic Git Training; using tools like Visual Studio Code, we created internal training on how to fetch, commit, and submit pull requests
• CI/CD Training; the nDocs application in BuildMaster gives them hands-on experiencing using our product to test and deploy changes to production
• One-click Webserver; a basic executable they can download that spins up a web server, reads files from the content directory, and lets them browse the site
• Local Debugging Experience; some small features in the local version, like a “click to edit” button that make it easier to work with content
• Documentation for Documentation; a basic guide that explains the nonintuitive portions and formatting that serves as a supplement to training

As for the name of this proprietary CMS, I went with “nDocs”.

The “n” obviously stands for new. Or maybe it’s the “n” in Inedo. But I’ll be very upset if says it’s “nightmarish”. Who would call a program that!?

Another Benefit of nDocs

Forcing our nontechnical members to use nDocs, and the engineer-driven process behind it, will also help them empathize with our end users. They’ll learn what it’s like to have a test and production site, evaluate “diffs” and “commits” before a release, and feel the stress of that “deploy” button.

And if they “break” the docs site by shipping wrong content – as I’m sure will happen some day – they’ll learn how easy it is to troubleshoot, rollback, and restore without stressing out.

Ultimately, we’ll give them just enough rope to not hang themselves.

Contributing to Inedo’s Documentation

Our documentation content is in GitHub and everyone is welcome to contribute. Every article in Inedo Docs has a little Octocat icon that links directly to the source file.

Realistically this means that readers can help fix typos and correct other errors. Those tend to be the hardest thing to spot when writing, especially after we’ve been starting at the document for hours.

If you have any higher-level feedback, don’t hesitate to post to the Inedo Forums. Or you’re welcome to contact me directly, I’m always happy to hear from users.