-
Notifications
You must be signed in to change notification settings - Fork 5.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Optimization and Clarity Enhancement for Intro to Plugins Documentation #23266
base: master
Are you sure you want to change the base?
Optimization and Clarity Enhancement for Intro to Plugins Documentation #23266
Conversation
Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for picking this up 🎉, excited to see this guide start moving!
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>
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the work your doing on this @markjacksonfishing, finally got some time to look this over.
|
||
![plugin](../assets/plugins/my-plugin_screenshot.png) | ||
![Plugin Screenshot](../assets/plugins/my-plugin_screenshot.png) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should really take the time to update this image as it doesn't match the current state
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@awanlin I could add to the 101
section Integrating with external systems: Interfacing with APIs and other services.
and reword the 301
section to Enabling resource-level authorization and interfacing with SCMs or databases.
- 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do like "Bringing Your Plugin to Production"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How about:
- Preparing Your Plugin for Production
- Strategies for growing the usage and adoption of your plugin.
- Best practices for monitoring and logging.
- Understand plugin ownership and maintain an inner source mentality.
|
||
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@awanlin I could list the sections under Guides for Plugin Development
without the level of sub-headings, or I could use more descriptive sub-headings without the numbering system.
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 |
…grator-guide-21945
Co-authored-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Signed-off-by: Mark Jackson <16655670+markjacksonfishing@users.noreply.github.com>
…files#r1588028883 Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
…21945' into feat--write-an-integrator-guide-21945 Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
Signed-off-by: markyjackson-taulia <marky.r.jackson@gmail.com>
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! |
Hi @markjacksonfishing, I saw you push some commits but wasn't sure if you wanted me to review again. Can you let me know, please? |
@awanlin no review yet. More coming 🥳 |
Will have some today to add |
Currently working on diagrams |
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-by
line in the message. (more info)