Choosing the documentation strategy that works for you.

Pay attention to product documentation

Here's a wakeup call, are you aware that many organisations are successfully using product documentation as a means to stand out and differentiate themselves? Well, besides usability (UX) and customer experience (CX) design, developer experience (DX) is now one of the primary factors driving business decisions about how products are defined and designed, including its documentation.

Earlier, when documentation was the static digital reincarnation of product guides, there was a clear division of labour. While the technical writers worked with content management systems (CMS), the developers coded using different, more powerful tools such as the integrated development environments (IDE).

Gone are the days where documentation meant just text and diagrams. Today, it comprises of rich, real-time, interactive media content that has the power to redefine immersive customer experience.

Documentation is designed to help early prospects interact with your product, easily find information to learn about it in a fun way. It has evolved into a creative, three-way collaborative process between developers, technical writers and customers. This change has come about due to the widespread acceptance of agile development, serverless computing and the Cambrian explosion of APIs as the primary means of interacting with products or integrating them for building newer solutions.

A case in point here is Stripe. It has revolutionised the way payment gateways work for mobile apps and the digital economy. Stripe customers love their clear, well-laid-out, beautiful documentation that has played an important part in not only generating user momentum around the product, but also accelerating its adoption.

Stripe has successfully leveraged its documentation as a growth hacking marketing tool while keeping a sharp ‘developer-first’ focus, setting industry standards around developer experience.

So what is static documentation and how is it different from the dynamic one?

As an example, check out the electronic edition of any typical newspaper.  It is something that you can access via any mobile device or your computer and it stays the same each time you access it, today, tomorrow or anytime later. It is almost never updated. In contrast, dynamic documentation refers to content that comprises of rich media (images, video, executable code etc.) that is live, continuously updated in real-time. Think of the breaking news page of your favourite news provider. You will find the latest breaking news or context-sensitive advertisements that keep changing in real time. That is the power of dynamic documentation.

If static documentation is like using over the shelf (OTS) software that is installed and deployed once and used forever on your personal computer in non-internet era of no dynamic upgrades, then dynamic documentation is akin to modern day mobile apps which are upgraded on the fly and keep refreshing their content and capabilities continuously, such that users always have access to the latest information.

Content management market needs & trends

Content creation is no longer an isolated or post-product-development task relegated to specialised writers.

Technical writers have traditionally preferred to use tools that offer WYSIWYG editors and enables them to focus on the technicalities of the writing and publishing processes. These include structuring content, drafting, reviewing, versioning, and publishing. Developers, on the other hand, are closely and deeply involved with the product development processes. They prefer tools that are easy to integrate with in the developer workflows. For example, highly customisable and flexible editors, compilation and build management, collaboration tools, version control, DevOps and agile methodologies etc.

The current ‘developer-first’ trends fuelled by API driven products and the need for agile documentation have resulted in several innovations in product documentation. These include static site generators (SSG) and managed documentation hosting services.

Managed documentation services enable users to focus on the writing process itself without bothering about the documentation build and hosting processes.

Services such as  GitHub Pages, NetLify, Pickles and Aerobatic help in implementing static documentation strategies through the use of tools such as Hugo, Sphinx, Jekyll under their hood. Unlike these, managed services such as Developerhub.io provide dynamic documentation tools that not only offer better reader interaction and richer customer experience but also a more familiar working and collaboration environment for both developers and technical writers.

Let us take a look at the benefits and shortcomings of static as well as dynamic documentation before summing up on the key factors that can help you decide which strategy is good for your specific use case.

Static documentation

You can implement static documentation strategy through the use of static site generator tools directly or by using one of the managed services that is built around them. The latter takes away the pain of managing builds and hosting your documentation and allows you to focus on simply writing the content.

Static Documentation - Pros

Here are some of the reasons why static documentation has become so popular in recent times.

Fast

Static documentation is lightning fast in terms of reader access. There is no database connection or backend processing needed to display the information to the readers.  Once static documentation is built and generated, it is incredibly fast to serve and can be accessed over the internet using any supported mobile device, anywhere.  With static documentation, you can reach your target audience really fast.

Compact and cost-effective

If your product documentation involves only a few dozen pages that are infrequently updated and can be managed by product developers, a full blown content management system may be an overkill. In such a scenario, static documentation may serve you well, ease development and reduce costs.

Scalable development model

Static documentation using SSG tooling integrates well with current product development methodologies. As a result several developers may be coding APIs and simultaneously documenting them. This is a highly scalable development model that works better in agile development environments as opposed to the lock-step, serially developed documentation that lags product development. Unlike traditional documentation environments, in case of static documentation tooling, documents can be generated, reviewed and updated in parallel by several collaborators including developers and technology savvy technical writers.

Secure

Static documentation doesn’t involve a backend database or any software that can be hacked into. It comprises of statically generated web pages or files that are read-only and require no user interaction or feedback such as filling up forms. Unless someone really messes up with the file permissions while hosting the information, static documentation has no security issues.

Easy to host

It is fairly easy to host static documentation website, especially with incredibly fast Nginx, for example, as there are no complex server-side processes to worry about. You can even use a password protected File transfer mechanism (FTP) to share your static documentation.

Static Documentation - Cons

Despite its popularity and wide acceptance, many products are struggling with the challenges posed by static documentation.

Productivity challenges

Static site generator tools lets developers have control over documentation styling process. They love the fact that many of these SSG tools are programmatic. However, for traditional technical writers, static documentation tooling presents a steep learning curve and potential productivity loss challenge. Static site generator tools require the user to be comfortable with Markdown, code and version control. Those used to working with traditional CMS and WYSIWYG editors find it hard to learn programmatic syntax and figure out complex content linking, cross referencing directives. For many technical writers, having to work with developer workflows, build and deployment mechanisms is not fun at all.

Limits hiring choices

As true of any new technology, documentation development hiring efforts are constrained to only those technical writers who know how to use the tooling and frameworks for static documentation generators.  This can significantly limit your recruiting efforts if you are a small organisation or strapped for cash. Many of the C level executives, and product managers too, have good ideas and inputs for product documentation. However, the static documentation tooling restricts contribution to only those who are familiar with SSG tools and software development processes.

More content, less speed

Static documentation process scales linearly with the amount of information that you need to host. This is because all the pages are generated at once as part of build and publish process. It can be a problem for sites with thousands of pages, hundreds of documents and posts. Each time there is an update to any content or addition of new pages, the entire lot of static documentation needs to be re-generated, built and deployed.  Product that have huge volume of content experience slower documentation generation with static site generator tools. This behaviour worsens as more and more content gets added.  There may be workarounds but those involve deeper technology know-how. Scaling is painful with static documentation.

No Real time updates

Static documentation cannot create real time data on the client side. Thus it presents a limited customer experience for your products since it is a one way interaction with your readers.  It cannot offer interactive facilities such as customisable personalisation, user logins, form-filling, discussion forums without having to deal with some deployment and plug-ins or extension jugglery. This can also increase your build complexity and dependency issues.  In case of managed static documentation services, you are limited to the customisations and personalisation configurations offered by the provider.

Exporting data

You may not be able to easily copy-paste or export data from your static documentation lot into a different content management system.  You can check in any time but you can never leave (easily!). Some of the managed static documentation sites may provide you with capabilities to achieve this in a limited fashion. This can be an issue for products that need to integrate with larger offerings or organisation wide documentation publishing systems.

Dynamic Documentation - Pros

Dynamic Documentation provides a more holistic customer experience with the desired speed, scale and flexibility. Following are some of the benefits:

Higher documentation productivity

As compared to static docs, there is far more user focused customisation available with dynamic docs. The latter simplifies and accelerates the rate at which documentation can be updated, reviewed, published and accessible to the user. The combination of dynamic docs plus a managed service saves up so much time, from previewing, hosting, pushing/pulling updates, and customising content.  Companies such as Qiscus moved from their own implementation of a custom site, to DeveloperHub.io because it saves them 2-3 hours per week rather than having to fiddle with text/code and servers or worry about limitations of static docs. Managed dynamic documentation services have levelled the playing field between developers and technical writers, especially when it comes to leveraging the documentation tooling and product documentation content creation.

Simplicity at scale

Static documentation tools are file based and that limits their scale and speed in terms of accessing or updating data.  Dynamic documentation services, such as that offered by DeveloperHub.io, are database oriented. The customer need not worry about any building or deploying of documents as part of the publishing process as it is abstracted through a managed service. Use of database gives it an edge in terms of scale and managing websites. This is especially true in the case of higher volume of documentation content and/or higher frequency of changes and updates to the information as compared to static sites.

Goldilocks flexibility

Static site generator tooling is totally loose, programmable and flexible to the point that it scares non-technical writers. They get swamped with too much customisations and having to deal with various new constructs that may not necessarily relate one-to-one with the typical writing and publishing structure of documents. Dynamic services such as DeveloperHub.io have product documentation structure built from ground-up. It meets the modern products documentation structural needs as it is built around a “framework”. This framework helps users to get started with writing documents faster with just the right amount of flexibility required for popular customisations and personalisation.

Real-time experience

By their very nature, dynamic documents provide data in real-time. You have the ease of plugging in user data dynamically. Let’s take the case of a scenario where a budding new product undergoes a series of ‘name’ changes as it nears its early release. This can cause a flurry of activities when using static documentation. That is not the case with dynamic documentation. Features such as ‘variables’ in managed dynamic documentation such as Developerhub.io offer mechanisms to carry out real-time textual changes in a simple, painless manner that boost documentation productivity. Product name change can be as simple as changing the text project-wide by just modifying the variable value in a single place. Variables are applicable either in a project-wide scope or version-wide scope. They are of two types -  internal and external variables. Internal variables are used to modify characteristics of documentation or the content by just changing the variable value such as product name or a feature name. For example, the text could refer to latest document version as %last_version%". This will be always shown to the user as what they set in the variable settings. This is so the variable can be used in multiple places, and you wouldn't worry about changing it. External variables can be used to bring in user oriented dynamic data values and create a more personalised experience. User ID, user name, API Keys, subscription plan, version used etc., can be handled with external variables.

Collaboration smarts

Dynamic documentation helps in smart collaboration between content creators and content consumers.  This can help in continuous evolution of information tremendously. Static documentation tools offer collaboration through tedious version control mechanisms geared for developer workflows. Dynamic documentation tools such as Google Docs and DeveloperHub.io offer collaboration features that are easy to use and help in shared content creation with effective collaboration from users across the globe.

Dynamic Documentation - Cons

There are many advantages in using dynamic documentation strategy. However, you need to be aware of its limitations as well.

Complex to deploy and manage

Unless you are using a managed documentation service such as DeveloperHub.io, dynamic documentation is not trivial to deploy and manage, given the complexity in tools involved and the level of technical expertise needed to get several open source technologies to work together in tandem. A typical dynamic documentation setup may require multiple software including web server, database, a server to host your files, content distribution network (CDN) and high availability.  If you have technology savvy technical writers, they may be able to handle it. But it takes their precious content development time, or the DevOps time for managing additional documentation tooling setup.

Security Risks

Interactive documents have a higher probability than static documents when it comes to security risks associated with malicious hacking. You need to work with your service provider to understand if there are any security loopholes and whether your managed documentation provider has the requisite security checks and balances in place to ensure secure hosting for your dynamic documents. Managed documentation service providers such as DeveloperHub.io secures your documentation by protecting both data at rest and in transit using AES-256 encryption. Besides these, it uses a secure TLS connection for accessing any documentation published via Developerhub.io using industry-leading and secure AWS services.

Summary

Your product documentation is the window to your product’s effective usage and a growth hacking marketing strategy itself. Keep the following considerations in mind before choosing static or dynamic documentation tools and strategies for building your product documentation.

• What is your product documentation sizing in terms of overall documentation requirements, volume of data (text, images, dynamic content), complexity of content (storage, access needs)? Small number of pages or files are no problem with static content management. However, scaling could be an issue with SSG.
• What is your target user base and what are their support requirements? Is the frequency and volume of updates low or high? Content that rarely changes is better handled with static documentation.
• What is your current documentation team’s skill level? Are the developers effective writers as well or are there non-technical writers who develop content for your product? Are they familiar with static documentation tooling? Can you afford the steep learning curve for such tools? Managed dynamic services are better than self-managed content management systems, if your writers are not technology savvy.
• What are your documentation hosting and deployment needs? Can you leverage in-house product DevOps teams for your product documentation building and deployment pipelines and storage in code/doc artifactory? Or do you need to set it up from scratch or do you wish to utilise your time and resources better with managed documentation services? For some teams, it may work better to leverage in-house technical and operational (DevOps) skills for content development and documentation hosting, if you already have them as part of product development team. This is assuming developers have the requisite bandwidth to devote to documentation. However, in small teams where developers have no bandwidth to devote to documentation or tooling setup, and require help from technical writers, a managed documentation service is more cost effective and better use of limited developer resources.
• Are your documents highly interactive and require client side processes, data gathering, sharing such as forms, surveys, feedback, discussion, comments, collaboration? It is better to use dynamic documentation if your content requires customer interaction and feedback. If not, you can use static documentation - managed or unmanaged as per your budget and resource competency.
• Is your product documentation process highly collaborative and requires team-work between developers and writers who may not necessary be technical? Are your developers fully loaded with development work and need to spend minimum time in transferring information to technical writers who can produce elegant, well structured product documentation without necessarily overcoming steep learning curve of modern documentation tooling? In this case, a managed documentation service will work best in terms of boosting your team’s overall productivity and documentation agility.

Written by Shaloo Shalini, edited by Zaid Daba'een, for DeveloperHub.io.