If you have publicly available documentation for your product, open source it!

Even if all of your other software is proprietary, your documentation is a great candidate to be open sourced. For several reasons:

1. Everything is already public

Most docs today are some flavour of Markdown that is compiled with a static site generator to a static website. Unless you wrote a custom static site generator, there is nothing novel about your docs site. The content is public, and the site generator is probably FOSS anyway, so the git repository can be public, too.

2. Docs are easy to contribute to

Fixing a software bug requires writing code. Contributors need to set up a build environment, which is often time-consuming. Personally, I mostly contribute bug fixes to Android projects, because I already have the Android toolchain installed on my laptop. For other software (iOS, desktop, NodeJS, Ruby, etc.) I only open issues.

By contrast, fixing a typo in the docs requires editing a Markdown file. All I need is GitHub/GitLab. I can do everything via the web GUI: fork your repo, create a branch, edit the file, create a pull request. I can even preview the rendered Markdown directly in GitHub/GitLab.

This makes documentation a natural candidate for getting started in open source. For new contributors, but also for your company (if it is new to doing open source).

3. The git-based workflow is more time-efficient (for you and me)

Documentation fixes are often small, from a simple typo to a few lines of text.

For me, it takes roughly the same amount of time to “fork, edit, make PR” as it takes me to “write e-mail to support, explain to them where in the text the issue is, what the correct text should be, and convince them that ’no, I don’t actually have a question, I just want to report an issue’.” Both approaches take the same amount of time, but git is much less stressful for me. It is more precise, less verbose, and less back-and-forth.

For your team, git saves A LOT of time. Reviewing my PR with a few lines of English text in Markdown is trivial. Review, press merge, your CI deploys. 5 minutes of effort. On the other hand, consider this: having your support staff answer my e-mail, forwarding the information to your technical writing team, creating a ticket, having them do the work of making the edits, committing them, creating a PR, moving the ticket to done. That is a lot more work. Work that you can outsource to me save by simply open sourcing your docs.

When not to open source docs

There are some situations where you may not want to open source your docs, at least not directly:

a. Keeping unpublished drafts private

This blog is currently not open source. This is because I often write posts to get them out of my brain, but later decide not to publish them. I like keeping them around and tracked in git for my own reference, but I don’t want the world to read my half-finished thoughts.

In technical writing, too, you can encounter the need to keep documentation private: e.g., while preparing documentation for an upcoming, not-yet-announced feature.

And in software development this also happens: e.g., the fixing of embargoed security issues often happens on a private fork.

Your choice depends on how often you find yourself in such situations: are they one-off or regular? Therefore, do you keep all docs closed, or do you set up a private repo when the need arises?

Conclusion

Note that open source != FOSS. You can publish your docs under whatever license you like, and optionally have contributors sign a CLA.

Additionally, you can keep your existing processes of getting feedback from non-git-savy customers via your support portal and your feedback forms, and manually feed that back into your docs. Handling PRs just complements these methods.

As a developer/sysadmin/engineer/etc, I use publicly available docs every day. Whenever I stumble over an issue, I like to see it fixed, so that the next person doesn’t have to suffer the same confusion. I have made PRs with doc fixes to projects as big as GitLab and Google’s Flutter, but also smaller to ones like OPNsense. This would not have been as smooth and pleasant for both me and their product/dev teams had the docs not been open source.

So please make it easy for drive-by contributors to fix your docs – open source them!