Backstage TechDocs vs. Port: Modernize your internal documentation

Problems with internal documentation

Engineering organizations have always relied on internal documentation to share knowledge. Veteran engineers will remember the era of scattered Word documents or wikis with useful and less useful articles, which eventually gave way to centralized documentation platforms like Confluence. 

But internal documentation suffers, and has always suffered, from a fundamental problem: it relies on manual updates, which makes it inherently unreliable. Let’s be honest, updating docs is one of the most frustrating parts of engineering. Keeping documentation up to date doubles the effort of almost every engineering task — first doing the actual work, then documenting it properly. Developers don’t want to be writing docs or maintaining them — writing code and shipping features is exciting; updating Markdown files is not.  

In this blog post, we’ll dive deeper into the challenges of documentation, including TechDocs, and explore how internal developer portals like Backstage and Port address these issues.

The impact of stale internal documentation

Even in organizations with strong documentation cultures, docs go stale because engineers prioritize building over documenting. Engineers move fast — APIs change, frameworks evolve, infrastructure gets reconfigured — but documentation often lags behind. According to the 2025 State of Internal Developer Portals, only 6% of engineers update their documentation daily, while up to 43% of developers update docs just once per week. 

The impact of inaccurate documentation is bigger than just a minor inconvenience. When developers rely on stale information, they are more likely to waste time troubleshooting non-existent issues, setting up services incorrectly, or tracking down colleagues to get clarification. A single outdated line in a setup guide can break an entire workflow, leading to inefficiencies, misconfigurations, and even security risks. 

The worst part? Engineers often don’t realize the docs are wrong until they’ve already gone down a rabbit hole. This is why only 3% of engineers fully trust their documentation repositories, as highlighted in the latest State of IDP report. Docs go stale, and when they do, they slow everything down.

This is why internal developer portals like Backstage and Port offer a better alternative — by replacing static documentation with automated workflows and self-service solutions, they eliminate the reliance on manual updates and keep engineers moving forward.

What are Backstage TechDocs?

Backstage, an open source platform for building internal developer portals, offers a TechDocs feature that allows you to write documentation as code inside of your portal. Released in 2020, Backstage TechDocs is an early attempt to tackle the problems of documentation. The organization claimed the plugin would make documentation easy to create and find — ensuring that people actually use it.

TechDocs takes a docs-as-code approach to documentation literally: they put documentation and code right next to each other. The idea is that because both code and docs are side-by-side, you’ll be more likely to fix the docs as you fix the code. This also removes the friction of switching between systems to fix the docs.

This is also the biggest advantage Backstage TechDocs seems to offer over options like Confluence: you can write docs in the repository. Though this is an advantage, and in some cases makes a difference, is it really necessary? 

The types of internal documentation

To answer the question on how to solve documentation, or attempt to solve it at least we first need to understand what categories of documentation there are. We believe internal documentation for engineering organizations typically includes several key categories. Here’s a structured breakdown:

• Knowledge sharing & best practices: These are your engineering playbooks, coding guidelines, security protocol, and performance best practices, and includes documentation for deprecated services or migration plans.
  ‍
  
• Internal tooling & platform documentation: Guides on how to operate internal tools, services, and developer platforms. These typically serve as instructions for onboarding new engineers to the platform.
  ‍
• ‍Process documentation: These include notes on your team rituals: dailies, retros, planning meetings, tech design reviews, onboarding processes for new engineers and teams, incident management and postmortem documentation. You may also include compliance and security policies here.
  ‍
• ‍System & architecture documentation: Microservices catalog, including ownership, dependencies, and versions; API documentation for endpoints, request/response formats, and authentication details; infrastructure diagrams and architecture decisions (ADR logs).

• Troubleshooting & operational docs: Runbooks for handling common operational issues. Debugging guides for production incidents. Deployment and rollback procedures.
  ‍
• ‍Product & feature documentation: Internal specifications for upcoming features. User guides for internal stakeholders (e.g., how non-engineering teams interact with certain tools). Release notes and change logs.

What TechDocs don’t solve

TechDocs primarily make it easier to write and store documentation — especially for engineers who prefer maintaining docs in code. It includes a search capability and a compilation process that converts Markdown into HTML for easier viewing. 

However, while this helps, it doesn’t necessarily make consuming docs easier. Platforms like Confluence, Notion, and Google Docs have invested heavily in advanced search, AI-powered recommendations, and collaborative editing, making it faster to find and interact with the right information. Internal developer portals often consume docs for engineers, and present the concepts they contain in visualizations like blueprints. 

If an engineer still struggles to locate relevant documentation, their problem is more likely related to findability or stale docs, than a lack of documentation.

More importantly, not all documentation problems should be solved with more documentation. When looking at different categories of internal docs—such as process documentation, microservice catalogs, and troubleshooting guides—some of these are much better handled through automation instead. What if, instead of writing a guide on how to request access to a database, you could provide a self-service action that grants permissions instantly? 

Instead of maintaining a static list of services and their owners, an internal developer portal can dynamically generate and update that information. For many operational and platform-related needs, replacing documentation with automated workflows and golden paths can drastically reduce friction and improve the developer experience.

There’s also a deeper cultural issue that TechDocs alone doesn’t fix: the lack of a strong documentation culture. If an organization doesn’t prioritize writing and maintaining accurate documentation, no tool will magically create a culture of accountability and ownership. 

Without real-time documentation updates and human review, institutional knowledge gets lost—making it harder for new hires to ramp up, engineers to respond to incidents, or teams to collaborate effectively. The problem isn’t just about where documentation is stored; it’s about fostering a mindset where engineers see documentation as a shared responsibility. 

If documentation quality is the real challenge, what’s needed isn’t just a TechDocs implementation, but a company-wide initiative with clear expectations, incentives, and even scorecards to measure impact and maintain quality with future releases.

How to create modern documentation

Modern engineering documentation isn’t just about writing better docs — it’s about reducing the need for written documentation in the first place. By prioritizing automation, discoverability, and quality control, organizations can make documentation more useful, less burdensome, and easier to maintain. 

Instead of writing extensive documentation about tasks like creating a new storage bucket, requesting permissions, scaffolding a service, or integrating with legacy systems, internal developer portals can automate the entire process. The portal’s golden paths and self-service actions eliminate the need to write manual instructions, and the service catalog and blueprints visually represent all of your services, environments, and their dependencies in one place. 

This allows engineers to simply fill out a form—entering details like service name and owning team — to create a fully provisioned service with all the necessary configurations. No TicketOps needed.

Here’s a step-by-step guide to creating a modern, effective documentation strategy using an internal developer portal:

1. Prioritize automation over static docs

Instead of writing extensive guides for operational tasks, replace them with self-service actions that eliminate the need for manual execution.

• Replace runbooks with self-service actions: Instead of a troubleshooting guide, provide an automated script or workflow that fixes the issue.
  
  Example: Instead of a “How to Restart a Service” doc, offer a one-click restart button inside your internal developer portal. Or instead of “How to create a K8s cluster” offer this SSA:
  

• Automate access management: Instead of writing a doc on how to connect to a remote database, offer a self-service action that generates ephemeral credentials. This ensures security best practices and removes the burden of credential management from developers.
  
  
• Automate infrastructure requests: Instead of step-by-step instructions for provisioning cloud resources, create golden paths where developers input a few parameters and get a fully configured environment.
  
  Example: A self-service form that spins up a Kubernetes namespace instead of a doc explaining how to do it manually.

2. Centralize documentation with service & API catalogs

One of the biggest problems with traditional documentation is fragmentation—docs are scattered across wikis, repositories, and internal tools. Instead, centralize them in a developer portal.

• Build a service catalog: Instead of maintaining API docs in separate markdown files or Confluence pages, attach OpenAPI (Swagger) specs to each service inside your IDP (like Port or Backstage). Present documentation in a visually appealing, interactive format so developers can easily explore endpoints.
  
  

• Standardize onboarding & service metadata: Each service in the catalog should have an owner, description, README, API reference, dependencies, and operational runbooks all in one place.
  
  Example: A fully integrated microservices catalog where clicking on a service provides all relevant documentation in a single view.

3. Enforce and track documentation standards with scorecards

The best way to ensure high-quality documentation is to measure and enforce it. Use scorecards to track documentation coverage and automatically flag missing or outdated information.

• Create a documentation scorecard: Check that every service has a README. Validate that API docs (OpenAPI specs) exist for all exposed services. Ensure every operational runbook has been converted into automation or at least kept up to date.
  
  Example: A scorecard in Port or Backstage that assigns a “Documentation Health Score” to each service.
  
  
• Incentivize documentation maintenance: Add documentation quality to engineering OKRs or team KPIs. Use CI/CD checks to prevent merging new services without a minimum required level of documentation.
  

4. Build a documentation culture

Tools alone won’t fix documentation problems—culture matters just as much. Without a strong documentation culture, even the best systems will fail because engineers won’t prioritize writing or maintaining documentation.

• Make documentation a shared responsibility: Documentation should be part of engineering best practices, not an afterthought. Example: Assign documentation champions in each team who oversee documentation quality.
  
  
• Encourage real-time documentation updates: Engineers should update docs as part of their workflow, not weeks later. Example: Require documentation updates as part of pull requests when modifying APIs or services, and consider preventing merges until documentation is uploaded.
  
  
• Foster a culture of accountability: If documentation is missing or outdated, teams should feel responsible for fixing it—not just a single person or docs team. Example: Use documentation scorecards to create visibility on which teams maintain good documentation practices and reward improvements.
  
  
• Onboard new hires with docs from day one: Documentation should be a key part of developer onboarding—new engineers should expect to both consume and contribute to it. Example: Make updating a README or API doc part of the onboarding checklist for every new engineer.

Conclusion

Documentation should be a byproduct of good engineering, not a burden. By focusing on automation, discoverability, and maintaining quality control, engineering teams can reduce their reliance on static, manual documentation and instead create a modern, self-sustaining documentation ecosystem. The goal is not to eliminate documentation but to make it as seamless and useful as possible—allowing developers to spend more time building and less time searching.