Are you building a unified documentation experience for your (internal or external) customers? Is your documentation landscape a heterogenous mess? Are you fighting political battles over tooling choices your company inherited because of mergers and acquisitions? Do you have a hard time convincing teams to write documentation in the “right” tool?
Large organizations typically have serious documentation scaling issues:
- teams go rogue and start using a broad range of tooling for their documentation;
- mergers and acquisitions add documentation teams with (working) divergent processes and tooling;
- docs-as-code repositories need to be republished for external audiences with varying levels of openness.
In this article we explain how mature CMS (Content Management System) web publishing tools (like Drupal, the CMS we used to build our Zero Gravity Developer Portal Solution) can help you address these problems.
Isolated Documentation Islands
Docs-as-code is a great solution for technical writers to collaborate with developers, but it tends to create documentation islands. A multitude of isolated documentation packages are exposed in various places, sometimes they even each have their own look and feel. As a result, discoverability (how do users know about a documentation package and where it exists) and findability (the user experience of finding the actual information they are seeking) become a serious problem. This fragmentation equally affects internal users and documentation managers.
A great example is how Backstage, a leading open source internal developer portal solution, uses a docs repo per project approach that makes it easy to spin up a new documentation repository for a team. Technical writers can manage documentation in the code repository the project team controls and share with their developer team.
Backstage solves the resulting discoverability and findability problem with federated search which can help to connect the isolated documentation islands.
However, when you want to expose these internally generated documentation repos externally, organizations often need to apply stringent access control and want to update and control branding and styling. They might need to share certain documentation only with partners or customers, and styling needs to always be on-brand.
That is why we recommend teams that are implementing Backstage as an internal platform portal, to also have a separate external (interface) developer portal.
How do you combine an enterprise-wide information architecture with a docs-as-code authoring approach?
Developer Documentation Hub as a Solution
A (Drupal-based) Developer Documentation Hub that consolidates or republishes documentation from across the organization makes it possible to create a unified information architecture. This has several major benefits:
- If it isn’t broken, don’t fix it: Documentation and developer teams from across the enterprise that already have developed successful documentation practices, can keep authoring the way they are used to. At a later stage, when you already are successful, you can organize a change initiative to get all teams on a common standard process if that makes sense. If you need to convince teams to change their processes to even start being successful, you risk getting stuck in political battles.
- Roll out docs-as-code practices where docs are broken: A central documentation platform team can provide tools and best practices to help teams implement better documentation practices where they are missing.
- Teams can still document software projects independently from the broader organization.
- The documentation platform team can review and combine documentation from across the organization into a single Documentation Hub that is adjusted to the needs of the business. This includes:
- a single documentation portal,
- consistent branding and styling,
- access control,
- capture intent signals for marketing,
- benefits of a mature CMS like SEO (Search Engine Optimization), localisation, internationalization, accessibility,
- possibility to build a community,
- and more.
As we can see, with all product documentation managed by Drupal, we can now apply the full range of options a mature CMS affords. This CMS empowers a developer relations team in that very complex use cases are feasible, while all content is managed by one comprehensive system.
The central Developer Hub gives you governance, while allowing teams to produce documentation separately.
If you want to know more about how to solve these problems or about the solution we offer, get in touch with us.
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
