🚀 Feature: Write an integrator guide

[dwelsch-esi]

🔖 Feature description

Write an integrator guide

Write a guide to developing plugins. Include step-by-step instructions to creating and deploying a bare-bones plugin. Include instructions for progressively more advanced integrator tasks, such as proxies, security, and integrating with specific systems. This guide is necessarily a "cookbook" of recipes for writing plugin functionality. Any integration project is by definition unique; this guide provides building blocks for completing a plugin, but can't provide an end-to-end solution. Organize under Integrator in the doc TOC.

Audience: Integrator

Type: Task

The existing documentation might contain helpful source material that you can pull into this doc change. See this catalog of the existing (at the time of the CNCF tech doc analysis) Backstage technical documentation pages:
https://github.com/cncf/techdocs/blob/main/assessments/0008-backstage/backstage-doc-survey.csv

🎤 Context

This issue is a recommended change resulting from an analysis of the Backstage documentation commissioned by CNCF. The analysis and supporting documents are here:
https://github.com/cncf/techdocs/tree/main/assessments/0008-backstage

✌️ Possible Implementation

Related material in the current doc:

• https://backstage.io/docs/integrations/
• https://backstage.io/docs/plugins/

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

• I checked and didn't find similar issue

🏢 Have you read the Code of Conduct?

• I have read the Code of Conduct

Are you willing to submit PR?

None

[github-actions]

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.

[markjacksonfishing]

I would love to handle this issue.

[awanlin]

Thanks @markjacksonfishing, I've assigned this to you. If you need any support of have questions please let me know. I've been down this road myself several times so will have insights if you need it 👍

[markjacksonfishing]

Here's a high-level first draft to make sure I'm aligning correctly with the goal of the integration guide:

Backstage Integration Essentials: A Complete Guide to Plugin Development

• Guide Overview
• Foundation of Plugin Development
• Plugin Architecture Deep Dive
• Advanced Integration Techniques
• Deployment and Operational Excellence
• Adhering to Best Practices
• Troubleshooting and Support
• Real-world Implementations and Lessons
• Certification and Learning Pathways
• Resources

Would it be beneficial to open a Google Doc for drafting and refining? We could then link it here for easy tracking and visibility. If everyone likes this, we can 👍🏽, 👎🏽.

[awanlin]

I like it! Excited to see how this turns out. There is a good amount of existing documentation that could be included, it's just not organized very well or needs to be better fleshed out: https://backstage.io/docs/plugins/

As the docs are all Markdown feel like working on a branch would be easier. You'll have a lot of code examples which can be a bit "challenging" in a Google Doc. Also, then you are steps away from a PR ;)

[markjacksonfishing]

I've initiated foundational work #23266 on the documentation by optimizing the current structure. This initial effort aimed to understand the existing layout better and ensure the foundation was solid before starting to layer on the guide I've begun working on. This was a step of optimization to prepare for the following substantive contributions.

[markjacksonfishing]

I have the table of content currently here