As a technical writer, you are likely to have encountered both of the basic two approaches to delivering software documentation:
- Making the documentation fully open, public and available to everyone. This doesn’t necessarily mean that each and every page, section or document is public, but the majority of it is.
- Having some form of access control and making the documentation available only to clients, registered users or any other set of authorized users.
The sections below will analyze the benefits and drawbacks of both of these approaches.
Not (only) the Documentation team decision
As the section title says, this decision definitely isn’t, or at least shouldn’t be, the responsibility of the documentation authors. The availability of the documentation should, ideally, be a decision made jointly by the following functions in a company:
- Product management and strategy. It is up to product management to understand the audience, demand, competition and the general big picture when a feature is being released. If a feature is not fully completed or could benefit from testing by a limited set of external users to get important feedback, it makes sense to keep the documentation away from the public eye and leave it available to test users only. If a feature is something that shouldn’t be seen by competitors, at least for some time, again, hiding the documentation from the general public is valid. However, this kind of a decision is often left to a completely subjective estimate of the competent Product team members and there are hardly any clear indicators or metrics to support it.
- Marketing. Marketing can also provide valuable input into making such decisions. Public documentation can be a great tool to market available features, often even a better one than short feature overviews provided on company websites or landing pages. As documentation is more detailed and provides step-by-step instructions on how to use a functionality, it might also save a lot of demo time.
- Sales. If Marketing and Product agree that public documentation makes sense as a marketing and sales channel for a functionality or an entire product, there needs to be a funnel and an established process where Sales knows exactly how to handle incoming requests. This is key to making the entire pipeline of Documentation, Product, Marketing and Sales teams work seamlessly towards the goal of using documentation to make sales.
Technical challenges
If the ultimate decision is to hide the documentation content away from the public, this might present a new challenge to Documentation teams as many approaches require intervention from Engineering and/or DevOps to set up the selected technical solution, especially when using the docs-as-code approach that results in deploying a static documentation website.
Here are some of the ideas or solutions that can be used to distribute non-public docs:
- Distribution of PDF documents. This is a viable solution, especially if PDF is already the main format in which your documentation is published and distributed. However, there are significant drawbacks to this appraoch:
- Users might be using outdated documentation. Once PDFs are delivered, there is no guarantee that the user will always resort to the latest or correct version of the document. As a documentation author, you have no control over what is happening with the documents once they are in your users’ hands.
- You have no control over further distribution of the documents. Once delivered to the users whom you actually want to have the documents, they can distribute them freely to other people, and this probably doesn’t present the level of protection you’d like.
- Using cloud-based document authoring and collaboration tools such as Confluence, Google Workspace or Office365. This method is definitely more elegant than distribution of (PDF) documents via email or other channels, while at the same time providing the author more control over what content the users see and can access. Once shared to the user, the content stays in the author’s control and can be updated if and when needed, to make sure the most up-to-date version is served to the users. However, the fact that external users are given access to a tool that is likely also used by the company internally might spark some security concerns. In addition, there have also been cases of companies having to pay an additional license to completely separate the tool instance that is used internally, from the instance that serves the documentation and allows access to external users.
- Password-protected websites. If your documentation is generally distributed as a documentation website (portal), this approach definitely makes most sense. A part of the content or an entire documentation set can be password-protected, require user login through SSO, one-time password, or use a different authentication method. Any of the above, except from the exceptionally unsafe protection using a single password that is shared to all users, should be a good instrument of access control, while also providing a decent experience to users who are trying to log in and access the protected documentation. On the other hand, it is worth considering what the cost and effort of implementing such a solution are. If you are using a third-party CMS-like solution to create and publish your docs, some of these features might come with it, potentially involving additional charge to get them enabled. However, if you’re producing and hosting a static website and don’t already have a customer portal or a similar setup that would provide access control, this definitely is a much greater effort to configure and get it up and running, again involving not so insignificant costs.
Final thoughts
Without clear indicators on the extent in which fully pubic documentation boosts sales and has other potential benefits, or, on the other hand, presents a potential disadvantage as competitors might be able to see clearly what you’re building and how you’re implementing it, it is difficult to say whether public documentation is better than access-controlled docs, or vice versa. As already stated above, this decision is cross-functional and should be based on inputs and estimates provided by multiple different roles within the company. If opting for non-public documentation, this should, again, involve all of the stakeholders, potentially even including engineering, to discuss the optimal solution and implementation.
