Optimization and Clarity Enhancement for Intro to Plugins Documentation #23266
Conversation
Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
github-actions
bot
added
the
documentation
Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
|
This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution! |
|
@aramissennyeydd, I will incorporate these and my new work this week. Thank you for all the feedback! |
|
@markjacksonfishing Looking forward to it! |
|
This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution! |
|
@aramissennyeydd can you remove the stale label? I have work to submit but still working through it. |
|
@markjacksonfishing If you comment, it will remove the label if you don't have access to directly remove it, "shoo stalebot 🌬️ " is a favorite of mine. |
|
This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution! |
|
Still working on this after travels. |
|
This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution! |
|
I will have the updated committed by eod today. |
Signed-off-by: markyjacksonfishing <marky.r.jackson@gmail.com>
|
This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution! |
|
I am still working through this—a lot of material to pull in and adjust, but it is still in progress and active. |
|
Today I will have the edits addressed. |
Signed-off-by: markyjacksonfishing <marky.r.jackson@gmail.com>
Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
Uffizzi Ephemeral Environment - Virtual Cluster☁️ deploying cluster ⚙️ Updating now by workflow run 8774697010. Download the Uffizzi CLI to interact with the upcoming virtual cluster |
…ge/actions/runs/8774532449/job/24075832205?pr=23266) Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
…ns/runs/8774642005/job/24076059990?pr=23266) Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
|
I will continue debugging the GHA failure tomorrow. |
@Rugvip i will tinker with the GHA later this morning. |
|
@markjacksonfishing what's the GHA problem you're aiming to fix? |
@Rugvip, mainly this one, but I will be very transparent about the fact that the error could totally be me missing something. |
|
@markjacksonfishing @Rugvip I think something's up with the microsite build step, getting this error in #24069 as well |
@aramissennyeydd Yep, same thing. I attempted to untwine the ball o string here, but that opened a pandora error box, and I reverted it. |
Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
|
@aramissennyeydd, do the items I added to the outline look suitable? If so, I have more to add, but I want to ensure we are aligned. |
|
@markjacksonfishing LGTM, @awanlin and @vinzscam / @benjdlambert, can you also take a quick look? |
|
Sure, will give it a look. Also seems a conflict crept in. |
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
|
@aramissennyeydd if the table of contents is good, I will get moving (already have items). |
|
@markjacksonfishing Go for it! 🚀 |
There was a problem hiding this comment.
Thanks for the work your doing on this @markjacksonfishing, finally got some time to look this over.
|
|
||
|  | ||
|  |
There was a problem hiding this comment.
We should really take the time to update this image as it doesn't match the current state
| be presented as a part of a Software Catalog (e.g. a separate tab or a card on | ||
| an "Overview" tab), then check out | ||
| [the instruction](integrating-plugin-into-software-catalog.md) on how to do it. | ||
| Should your plugin complement the Software Catalog rather than exist as a standalone entity (for instance, as an additional tab or a card within an "Overview" tab), you'll find comprehensive guidance on achieving this integration [here](integrating-plugin-into-software-catalog.md). |
There was a problem hiding this comment.
Could we use a different word then "entity" here, it's a bit overloaded. I think you mean like the way TechRadar or Cost Insights are only access via the sidebar when you say entity here but for those new to Backstage that might not be obvious. We also uses entity to mean items in the Catalog so it's a bit confusing.
There was a problem hiding this comment.
Also, let's try and adjust using "here" for the link
|
|
||
| To create a plugin, follow the steps outlined [here](create-a-plugin.md). | ||
| Embark on your plugin development journey by following the detailed steps provided [here](create-a-plugin.md). |
There was a problem hiding this comment.
To help avoid using "here" as the link I like to say:
| Embark on your plugin development journey by following the detailed steps provided [here](create-a-plugin.md). | |
| Embark on your plugin development journey by following the detailed steps provided in the [Create a Plugin](create-a-plugin.md) documentation. |
| This is for those ready to explore complex challenges and enhance their plugins with advanced features. | ||
|
|
||
| - **Plugins 301: Advanced Topics in Plugin Development** | ||
| - Enabling resource-level authorization and interfacing with external services, SCMs, or databases. |
There was a problem hiding this comment.
I worry about this coming so late, general experience is that most initial plugins are based around: "I want to integrate with System X usually via its API".
| - Detailed guidance on starting and iterating on a plugin development project. | ||
| - Engaging with the community and stakeholders to propel your project. | ||
|
|
||
| ### For Intermediate Users: Scaling Your Plugin |
There was a problem hiding this comment.
Optional: Is "scaling" the right word here? What comes to my mind first is more technical - horizontal and vertical - that might also be what others think. I'm not sure what the better wording would be right now though 🤔
There was a problem hiding this comment.
I do like "Bringing Your Plugin to Production"
|
|
||
| This section is designed for those new to plugin development. It covers the basics and provides a foundation for more advanced topics. | ||
|
|
||
| - **Plugins 101: Building Your First Plugin** |
There was a problem hiding this comment.
Do we really need these headings for the lists? There's already a main heading that seems pretty clear. The 101, 201, and 301 terminology may not be universal.
| - In-depth exploration of fostering an inner source mentality and understanding adoption dynamics. | ||
| - Decision-making frameworks: choosing between developing a new plugin or utilizing an existing open-source solution. | ||
|
|
||
| ## Additional Resources and Further Reading |
There was a problem hiding this comment.
Is the intention to add links here? Right now this doesn't look to be terribly helpful 🤔
|
Just wanted to give an update that I am still working through the edits and new content. More to come this week. |
|
I just wanted to give an update that I will have a good chunk done in the next week. |
|
This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution! |
|
This is still ongoing. I have items ready, but I'm doing some final checks |
Hey, I just made a Pull Request!
Optimization and Clarity Enhancement for Intro to Plugins Documentation
This pull request introduces a series of enhancements aimed at optimizing the structure of the "Introduction to Plugins" documentation. The initial commit refines the document for clarity, readability, and markdown best practices, setting a solid foundation for further updates. Subsequent commits will address specific requirements and suggestions arising from issue #21945 on the Backstage GitHub repository.
Key Highlights:
Objective:
My goal is to ensure that the "Introduction to Plugins" section serves as a comprehensive, easily navigable, and user-friendly resource for both new and existing Backstage contributors. By aligning this documentation more closely with community feedback and the evolving landscape of plugin development, I aim to foster a more vibrant and collaborative ecosystem.
Invitation for Collaboration:
Feedback, suggestions, and contributions are welcomed to continuously improve this documentation. If you have insights or enhancements to propose, please feel free to comment on this PR or contribute directly to the discussion in issue #21945.
✔️ Checklist
Signed-off-byline in the message. (more info)