docs: add meta guidelines for new guides

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>
2024-11-10 12:26:28 -05:00
parent 0d5d4215ac
commit 4626abff6b
3 changed files with 51 additions and 0 deletions
@@ -0,0 +1,33 @@
+<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
+
+# Intro to Plugin Development
+
+## Writing Guidelines
+
+The goal of this section is to take the reader from zero-to-situated. Docs should assume that the user has _only_ gone through the initial getting started docs. At the end of this guide, the user will understand the basics of plugin development.
+
+### Why build plugins?
+
+This section should answer definitely why you should build a new plugin instead of adding code to existing packages or using an NPM package. The Backstage framework is deeply empowered by plugins and plugins are core to the project's success. Users should walk away from reading this section with a conviction that plugins are the right path for new functionality.
+
+### Creating a plugin
+
+This section should be extremely deliberate in showing readers every step of the way to create a plugin. A reader that finishes this section should feel extremely comfortable adding and installing new plugins regardless of their experience with JS/TS.
+
+- Setting up your environment
+- Scaffolding a new plugin
+- Installation syntax
+- Core services
+- Debugging
+  - Declaration error, `export default` missing
+  - Startup error, `httpRouter` failed to start
+
+### Sustainable plugin development
+
+Plugins are not developed in a vacuum. Users should reach for them to solve specific business problems facing their developers, for example, you may be tasked to create
+
+- a new vendor integration like PagerDuty,
+- a new plugin backend that talks to an internal service,
+- etc.
+
+This section should contain learnings from successful Backstage deployments about how to engage with stakeholders, how/when to iterate on your plugin, and setting yourself up for future success.
@@ -0,0 +1,18 @@
+<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
+
+## Glossary
+
+- Page: A single `md` file.
+- Guide: A number of pages grouped under the same folder.
+- Progression: Guides are ordered and moving along that order will give you the next guide, for example, "201" will follow "101" or "experienced" will follow "beginner".
+- Progression level: Explicit guides in a progression, for example, "101" or "beginner"
+
+## Writing Guidelines
+
+The goal of these docs is to provide a comprehensive set of guides that developers + admins can use to initially get quickly up to speed with plugin development, and then refer to as they're developing their own plugins.
+
+A user that finishes all of these guides will feel comfortable implementing plugins on their own for 90% of cases. For the remaining 10%, they will know where to find help (Discord, Github, source code). The user will also understand why/when to build their own plugins, inner-sourcing their developer portal and contributing internal plugins back to the open-source project.
+
+At the same time, not all users will finish the docs or they may come back to them as required. Individual guides should have strong "abstracts" (what will I learn by reading this guide), table of contents, and "next steps" (what do I need to do next) to guide users to read the most important pieces for their work.
+
+When writing guide pages, keep it light! These should be instructional docs, and at the same time conversational and a joy to read. Guides should build on each other, when reading through a progression, the reader should feel more comfortable and confident with concepts as they pop up across progression levels. Guides should be standalone, when finishing one level (for example 101), you should be able to immediately jump into the next (201) without additional research or background. Referencing previous progression levels is ok.