possible updates

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>
2024-03-19 09:30:03 +01:00
parent 6ec07d6aa1
commit 9a46050fa5
1 changed files with 122 additions and 74 deletions
@@ -79,6 +79,41 @@ The benefits of restructuring the documentation according to these ideas include
 - The Docs section of the microsite will be divided into two top-level sections: Framework and Developer Portal.
 - The structure of the Table of Contents will align with the outline proposed in https://github.com/backstage/backstage/issues/21946.

+### User Persona
+
+Documentation written for the user persona should be high level, assuming little to no technical knowledge. Concepts like the difference between Backstage Framework and Developer Portal should be explained at a high level to give Users a working knowledge, but should not be flushed out completely until we identify the user as a distinct user persona. Users may also be Administrators, Integrators or Product Managers, but documentation for Users should make no assumptions on that.
+
+Example explanation of Backstage Framework vs Developer Portal:
+"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. Backstage Framework provides the tools you need to build your own developer portal and Backstage Developer Portal is your custom developer portal built using the Backstage Framework."
+
+### Administrator Persona
+
+Documentation written for this persona should be DevOps technical, assuming a strong DevOps background with the exception of a Getting Started section. While we should assume an overall technical knowledge, where possible we should link out to existing strong guides for the technologies we use, ex: PostgreSQL, Docker, Kubernetes, etc. The goal with administrator documentation is to give administrators a strong understanding of how to deploy and manage a Backstage Developer Portal, best practices, and possible tripping points.
+
+Example explanation of Backstage Framework vs Developer Portal:
+"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. As an administrator, you will be interacting with Backstage Developer Portal primarily -- this is the running Backstage instance that you're managing. It is also useful to have a high level understanding of the Backstage Framework for mitigating issues or better understanding how to scale your Backstage Developer Portal."
+
+### Integrator Persona
+
+Documentation written for this persona should be software technical, assuming a strong software background with the exception of a Getting Started section. While we can assume an overall technical knowledge, where possible we should link out to useful guides for the technologies we use, ex: Node.js, express.js, React, etc. The goal with documentation written for integrators is to give them a strong understanding of where their work fits into their company's Backstage Developer Portal, orient them to get support from the open source community, and prepare them for continuing to deliver value for their Backstage Developer Portal.
+
+Example explanation of Backstage Framework vs Developer Portal:
+"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. As an integrator, most of your time will be spent working to deliver value on top of the Backstage Framework for your company's Backstage Developer Portal. This means creating plugins, theming your Backstage Developer Portal or adding integrations to internal data stores. You should have a strong understanding of the Backstage Framework and have a strong understaing of code that sits in your Backstage Developer Portal."
+
+### Business Stakeholder
+
+Documentation written for this persona should be strategic, assuming a strong background in business development and strategy. The goal for business documentation is to give a strong understanding of what Backstage Developer Portal can do for their company, how to deliver value quickly and continuously and guides for pitching or driving Backstage adoption.
+
+Example explanation of Backstage Framework vs Developer Portal:
+"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. As a business stakeholder, your time should be spent with your company's Backstage Developer Portal solely. This means understanding the value proposition of an IDP, what improving the developer experience at your company means and what a successful Backstage Developer Portal looks like. The Backstage Framework is the technical underpinning and will generally be invisible to you."
+
+## Contributor
+
+Documentation written for this role should be technical, but should make no assumptions on technical strength. The goal with this documentation is to onboard new contributors to the technical stack and layout of the project, setting expectations for how to write code, documentation or generally contribute to the library.
+
+Example explanation of Backstage Framework vs Developer Portal:
+"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. You will work with both the Backstage Framework and Backstage Developer Portal. Backstage Framework is the technical framework for Backstage Developer Portal. The Backstage Developer Portal is the end user for your plugins, documentation or other contributions. As a contributor, you will be working to influence either the Backstage Framework or plugins and Backstage Developer Portals across the world may use your contributions."
+
 ## Release Plan

 - Release the BEP by 03/24/2024.
@@ -92,6 +127,7 @@ None
 ## Example Table of Contents

 - Overview
+  - "The overview should introduce users to the concept of Backstage, what an IDP is, how to deliver value, why you should care about DevEx, etc."
  - What is Backstage?
  - Roadmap
  - Vision
@@ -101,13 +137,16 @@ None
  - Support and community
 - Framework
  - Architecture Overview
+    - "The arch overview should explain how the framework is structured, where plugins and instances fit in and how to understand the current design of Backstage."
  - Getting Started
  - Integrator/Builder Guides
    - Local Development
+      - "Prepare users for how to develop locally, debug problems, run tests, etc."
      - CLI
      - Linking in local packages
      - Debugging Backstage
    - Backstage core framework
+      - "Internal documentation."
      - Systems
        - Frontend
          - Old
@@ -116,8 +155,9 @@ None
          - Old
          - New
    - API Reference
-    - Tutorials
+      - "Internal documentation"
    - Building plugins
+      - "How to build a plugin, how to integrate it with other plugins, how to deploy and monitor it, and how to iterate on plugin development."
      - Intro to plugins
      - Existing plugins
      - Creating a new plugin
@@ -134,48 +174,51 @@ None
      - Backends and APIs
      - Testing
      - Publishing
-    - Home Page
-      - Customizing the home page
-    - Software Catalog
-      - Extending the model
-      - External integrations
-      - Catalog Customization
-      - API
-    - Software Templates
-      - Writing custom actions
-      - Writing tests for actions
-      - Writing custom field extensions
-      - Writing custom step layouts
-      - Authorizing parameters, steps and actions
-      - Migrating to react-jsonschema-form@v5
-      - Migrating to v1beta3 templates
-    - Search
-      - Overview
-      - Getting Started with search
-      - Search concepts
-      - Search architecture
-      - Search Engines
-      - How to Guides
-    - TechDocs
-      - Customizing TechDocs
-      - TechDocs add-ons
-    - Kubernetes
-      - Customizing the kubernetes plugin
-        - Authentication
-        - Proxy
-    - Permissions
-      - Overview
-      - Concepts
-      - Getting Started
-      - Writing a permission policy
-      - Frontend integration
-      - Defining custom permission rules
-      - Using permissions in plugins
-    - Designing for Backstage
-    - ADRs
-    - Accessibility
-    - References
+    - Core Plugins
+      - "How to leverage the existing plugins for your new plugin or customization options."
+      - Home Page
+        - Customizing the home page
+      - Software Catalog
+        - Extending the model
+        - External integrations
+        - Catalog Customization
+        - API
+      - Software Templates
+        - Writing custom actions
+        - Writing tests for actions
+        - Writing custom field extensions
+        - Writing custom step layouts
+        - Authorizing parameters, steps and actions
+        - Migrating to react-jsonschema-form@v5
+        - Migrating to v1beta3 templates
+      - Search
+        - Overview
+        - Getting Started with search
+        - Search concepts
+        - Search architecture
+        - Search Engines
+        - How to Guides
+      - TechDocs
+        - Customizing TechDocs
+        - TechDocs add-ons
+      - Kubernetes
+        - Customizing the kubernetes plugin
+          - Authentication
+          - Proxy
+      - Permissions
+        - Overview
+        - Concepts
+        - Getting Started
+        - Writing a permission policy
+        - Frontend integration
+        - Defining custom permission rules
+        - Using permissions in plugins
+      - Designing for Backstage
+      - ADRs
+      - Accessibility
+      - References
  - Contributor Guides
+    - "How to get started contributing to OSS."
    - Contributing to Backstage
  - Reference
 - Developer Portal
@@ -183,6 +226,7 @@ None
  - Getting Started
  - Administrator Guides
    - Developer Portal
+      - "How do I deploy, monitor, configure and verify my Backstage Developer Portal?"
      - Installing and Configuring
        - Database
        - Authentication
@@ -197,43 +241,47 @@ None
      - Upgrading
        - Keeping backstage up to date
      - Customizing
-    - Home Page
-      - Installing and Configuring
-    - Software Catalog
-      - Overview
-      - The life of an Entity
-      - Catalog Configuration
-      - System Model
-      - YAML file format
-      - Entity Reference
-      - Well Known annotations
-      - Well known relations
-      - Well known statuses
-      - Creating the catalog graph
-    - Software Templates
-      - Overview
-      - Configuring
-      - Adding a new template
-      - Writing a template
-      - Built in actions
-    - TechDocs
-      - Overview
-      - Getting Started
-      - Architecture
-        - Installing and configuring
-          - Using Cloud Storage for TechDocs generated files
-          - Configuring CI/CD to generate and publish TechDocs sites
-        - TechDocs CLI
+    - Core Plugins
+      - "How do I install and configure Backstage Developer Portal with plugins."
+      - Home Page
+        - Installing and Configuring
+      - Software Catalog
+        - Overview
+        - The life of an Entity
+        - Catalog Configuration
+        - System Model
+        - YAML file format
+        - Entity Reference
+        - Well Known annotations
+        - Well known relations
+        - Well known statuses
+        - Creating the catalog graph
+      - Software Templates
+        - Overview
+        - Configuring
+        - Adding a new template
+        - Writing a template
+        - Built in actions
+      - TechDocs
+        - Overview
+        - Getting Started
+        - Architecture
+          - Installing and configuring
+            - Using Cloud Storage for TechDocs generated files
+            - Configuring CI/CD to generate and publish TechDocs sites
+          - TechDocs CLI
+          - Troubleshooting
+      - Kubernetes
+        - Installing and Configuring
+          - Authentication
        - Troubleshooting
-    - Kubernetes
-      - Installing and Configuring
-        - Authentication
-      - Troubleshooting
-    - Search
+      - Search
  - Product Manager Guides
+    - "How do I present Backstage to leadership, what are the benefits, why should I care, etc."
    - Strategies for adopting
    - Use cases
  - User Guides
+    - "How do I use the default OSS Backstage"
    - Logging in
    - Registering a component
    - Creating a new component