Open Sourcing Docs in a Closed Source Startup

With some of my latest posts, I’m trying out ideas for the #techdocscon portion of the Open Source Summit.

I’ve rewritten this post several times, which tells me that I’m having trouble defining some of my thoughts. I do have experience as a lone writer. Especially at startups, lone writers need access to others in similar situations. Lone writers can benefit from people to brainstorm with.

Such writers can benefit from open source. They can bring their issues to the community. But it works if (and frequently only if) they:

• Can share their work in progress
• Help others in the same communities

So how do you set up open source docs? Unless you’re working in an open source company, you need to overcome fear, uncertainty, and doubt. Overcoming these issues is worth some trouble. To do my best work, I need access to the open source community.

A disclaimer: I am not a lawyer or a security professional. However, I’ve worked with both for years.

Back to the problem at hand. To work with the open source community, at minimum, I needed a public docs repository.

To succeed, you need to overcome objections in (at least) two areas:

• Security
• Legal

Fortunately, the steps you take to address security issues can also (partially) address legal issues.

From a security point of view, you need to protect:

• Customer information: Unless you have explicit permission, you never want to name customers in documentation.
• Competitive information: If there’s a “secret sauce” for your products, you can not share that information with the “world.”
• Personally Identifying Information (PII): Of course, you must not reveal information about specific users. And that information can include “obscure” information such as OAuth 2.0 keys, SAML tokens, and even browser cookies.

From a legal point of view, you also need to protect:

• All proprietary information associated with your company.

Nevertheless, product documentation is information that you want to share with the world. Not only does it help your customers solve their problems, but also it helps convince potential customers to look at your products.

Even in open source, you want to prevent problems “up front.” You can set up style guides (and automated linters) that prevent you from publishing sensitive data. You want to avoid such problems even pull or merge requests. In an open source or a public repository, all of that information gets published.

Back to the legal questions. Today, lawyers who know software frequently have experience with open source software. Open source lawyers that I’ve worked with even suggested that I use a Creative Commons license!

With this knowledge in hand, you too can set up open source docs in a closed source company. Of course, you’ll need management support to make this happen, but that’s a different topic.