search

backstage / backstage

Backstage is an open framework for building developer portals
https://backstage.io/
Apache License 2.0
26.95k stars 5.61k forks source link

🚀 Docs: Enhancing Backstage Documentation: Personas, Framework, and Developer Portal #23689

Open waldirmontoya25 opened 3 months ago

waldirmontoya25 commented 3 months ago

🔖 Feature description

The proposed restructuring of the Backstage documentation revolves around two core ideas:

  1. Positioning Backstage as both a framework to build developer portals and a developer portal itself, and splitting the documentation into these two categories.

  2. Defining the personas participating in Backstage adoption journeys to improve documentation navigation. The identified personas are:

    • User: A person who uses Backstage to find information, use plugins, and consume the developer portal.
    • Administrator/Operator: A person who configures, secures, and deploys the developer portal, manages plugins, and oversees the general administration of the developer portal.
    • Integrator/Builder: A person who builds plugins, customizes the code and design, and creates custom-built developer portals based on the Backstage framework. This includes plugin builders, designers, and developers.
    • Product Manager/Business stakeholders: A person who defines the strategy for adopting Backstage, identifies use cases, communicates the value proposition for adopting Backstage and connects the developer portal to the business strategy.
    • Contributor: A person who contributes to the Backstage ecosystem.

The benefits of restructuring the documentation according to these ideas include:

  1. Easier navigation and discoverability of information for different personas and use cases.
  2. Clear separation of runtime and development documentation.
  3. Simplified process for contributors to determine the appropriate location for new documentation.
  4. Streamlined Backstage adoption process for new adopters.

🎤 Context

The current Backstage documentation has been reported to be difficult to navigate, making it challenging for different personas across the DevEx ecosystem to extract value. The CNCF assessment (https://github.com/cncf/techdocs/tree/main/assessments/0008-backstage/) and the resulting issues (https://github.com/backstage/backstage/issues/21893) highlight the need for improvement in the documentation structure.

✌️ Possible Implementation

Design

👀 Have you spent some time to check if this feature request has been raised before?

🏢 Have you read the Code of Conduct?

Are you willing to submit PR?

Yes I am willing to submit a PR!

camilaibs commented 3 months ago

Linking the BEP : https://github.com/backstage/backstage/pull/23692

github-actions[bot] commented 1 month ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.