DX content strategy with developer portals
As the content grows on a developer portal, there’s an increasing need for some technical writers to expand their documentation roles from individual contributors creating and publishing new content to dedicated content strategists. These dedicated content strategists manage the processes, standards, tools, governance, and workflows for the content that is primarily authored by contributing writer and engineering teams.
The general common industry term for this activity might be content strategy, but in the context of developer documentation, I’m calling this activity “DX content strategy.” (DX refers developer experience, similar to how CX refers to customer experience.) Anyone who engages in DX content strategy would be considered a DX content strategist to some degree. An organization can have multiple people filling DX content strategist roles.
- Risks of developer portals with no DX content strategy
- Tasks for a developer portal content strategist
- Bandwidth for all of these tasks
Risks of developer portals with no DX content strategy
If organizations don’t have any DX content strategists dedicated to their growing developer portals and enhancing the developer experience, the resulting trajectory of a developer portal will follow the same path more or less as an internal wiki. Internal wikis tend to be content dumping grounds that are a wild west of standards and styles, and where you never know if content is current, outdated, accurate, deprecated, or under construction.
Finding the right content on an internal wiki is a constant challenge, and there’s no consistency from one page to the next. In the wiki model, teams create docs during their times of need and abandon them when their teams or priorities change. The result is a mishmash of fragmented, often unowned content.
Because documentation for external developers is a high priority, it shouldn’t befall the same fate as content on internal wikis. In the State of API 2019 report, Smartbear found that “accurate and detailed documentation” ranked third in priority (just below “ease of use” and “responsiveness/performance”) from 15 ranking factors in an API experience. You can’t achieve a high level of content quality without playing a more strategic role with the content and expanding beyond the individual contributor model. Individual contributors are usually focused on docs for a current project only and rarely have bandwidth to expand their concerns at a broader, more encompassing level across the developer portal.
Additionally, the individual contributor model doesn’t scale for the typical engineer-to-writer ratio in most organizations — a ratio where engineers and other tech roles vastly outnumber writers. You might have just a handful of tech writers to support thousands of engineers. Tech writers often work with different product teams on a continually shifting basis, covering as much ground as possible but not having capacity to meet all needs. In this “itinerant” tech writer model, you can’t always play individual contributor roles to write the content that each product team needs. Instead, writers have to shift to playing more content strategy roles around content that others develop.
To elevate contributor contributions to any standard, you have to equip contributors with easy tools, simple markup, fill-in-the-blank templates, clear standards, careful feedback, immediate tools support, and other information and tooling for their effort. You can’t do this if you’re an individual contributor fully dedicated to three or more full-time projects — often without enough time to finish, let alone teaching and helping other contributors.
Overall, the DX content strategist provides the mechanism to elevate the content in ways that improve the developer experience on the portal. As a strategist, this elevation of content doesn’t come from creating better content yourself but rather from all the meta-activities you do around content development and publishing. At a high level, these meta content-development activities might include the following:
- Onboarding and training contributors (and providing materials to facilitate self-service onboarding)
- Providing standard templates and guidelines for content creation
- Defining processes and standards (such as for releasing SDKs or writing release notes)
- Making tools available that will automate content checks and workflows
- Defining authoring and publishing workflows and content reviews
These tasks don’t involve creating new documentation. Instead, the DX content strategist focuses on the many activities required outside of content development to ensure the content quality meets a high bar.
Tasks for a developer portal content strategist
The following sections expand in more specific ways on the roles, tasks, and needs that DX content strategists play with a developer portal. I’ve divided the tasks into general groupings related to tools, contributors, processes and standards, and information architecture. Depending on the size of your doc team (e.g., 5 writers versus 150 writers), you might have specialized teams focusing on each of these areas.
Tools
-
Set up, maintain, and enhance the authoring and publishing toolchain
-
Troubleshoot the build when it breaks, and then train contributors about proper usage of the system to avoid future breaks
-
Understand how the doc toolchain builds and publishes content from end to end (from static site generator outputs to build pipelines, CI/CD server deployments, and more)
-
Reduce the risk of Git catastrophes and broken builds in the system (such as due to misunderstandings with Git or insufficient safeguards with permissions)
-
Develop and enhance the doc theme’s design and style as well as the available components (e.g., navtabs, accordions, or menus) to use for different scenarios
-
Implement style/grammar checkers (e.g., Acrolinx) either with in-tool plugins or perhaps at the platform level
-
Build out and verify scripts (e.g., Travis CI scripts, GitHub Actions) to perform automated checking, such as looking for broken links or style inconsistencies
-
Integrate and configure the search experience (e.g., Algolia, Swiftype, other), including SEO and discoverability of content in search engine results
-
Define the metadata that feeds into the search experience to provide navigable facets or other structured data for search; also monitor the documentation to ensure contributors are using the right metadata
-
Address security tickets related to the developer portal (e.g., reverse tabnabbing, linking to external JavaScript sources, errant permissions)
-
Configure scripts for PDF generation and output (e.g., Prince scripts) to distribute content to pre-release partners
-
Manage the assets for your developer portal and permissions through the web console related to your website host
Contributors
-
Develop training and guides for contributors to onboard with the toolchain and authoring/publishing processes
-
Create templates for how-to content and other format types (release notes, getting started, first-time setup, CLI docs, schemas) to help guide authors as well as maintain consistency across docs
-
Define Git workflows and manage Git permissions for contributors, including pull request workflows and code review workflows
-
Create reports to assess each doc set to identify stale content (which hasn’t been updated for a long time), missing metadata, outdated localization, and other problem areas
-
Define a process for regularly auditing content to avoid stale, abandoned, or outdated content. Include timelines, requirements, and automated notifications to send out when content owners haven’t reviewed their docs for a long period of time (e.g., one year)
-
Create and maintain a list of contacts for every doc set, listing current owners and roles
-
Review and monitor Git commits from contributors to identify problems or other issues with contributor content
-
Analyze trending support tickets and hot topics (even when not filed against the doc team) and sync with engineering teams on resolutions
-
Identify support paths and escalation processes for the different products on the developer portal
Processes and standards
-
Define the process for managing large doc projects, including processes for releases that have impact across field engineers, marketing, and support, etc, not just docs.
-
Define a process for assessing incoming small doc requests and decide how to approach and prioritize them. Regularly groom the backlog so that you don’t have a sea of stale tickets.
-
Define and enforce the release process for SDKs, sample apps, and other code artifacts on the developer portal
-
Set up and define localization processes, priorities, and workflows with regards to doc tools
-
Define processes for granting access to docs prior to release for early access partners, such as during beta periods
-
Define and set up on-call workflows and rotations to handle incoming feedback, emergency tickets, or other daily doc emergencies
-
Define and enforce the doc review process prior to release, including any required sign-offs
-
Define processes for deprecating documentation, including outreach and notification workflows as well as migration/upgrade paths
-
Define strategies for versioning content, including approaches for incremental versions versus non-incremental versions, deprecated versions versus active versions, small version variants versus entire doc sets
-
Promote awareness of Legal red flags and danger zones (e.g., forbidden terms or IP violations), as well as the Legal review process
-
Define, implement, and enforce a docs style guide for the site. Also, define and contribute to an API design style guide and understand how it relates to documentation
-
Ensure that all docs (especially from contributing authors but also from other technical writers) meet common standards, including release notes for changes published, getting started tutorials, proper syntax highlighting for code samples, etc.
-
Define policies for when PDFs are delivered, how they are styled, what legal boilerplate appears on them, and how they are stored and distributed
-
Define and promote standards for API reference content, such as using OpenAPI with REST APIs
-
Define and review standards for tagging in auto-generated reference docs from library-based APIs (e.g., Javadoc, Doxygen)
-
Define process and standards for developer product naming and branding, and then enforce this against individual teams that might launch new feature names in unapproved ways
