search

Azure / azure-sdk-tools

Tools repository leveraged by the Azure SDK team.
MIT License
109 stars 166 forks source link

Release Plan - add documentation with visuals, user roles, and expectations. #7558

Open ladonnaq opened 5 months ago

ladonnaq commented 5 months ago

Requirement: Documentation in engineering hub with a step-by-step tutorial with screenshots of each of the release plan pages so that service partners can view before and see the steps before creating a release plan to use to complete work for publishing new API versions and releasing new SDK versions.

Topics to be covered in new docs page:

Use of screenshots on Engineering Hub does not align to design guidelines There were many questions from service partners when we first launched the onboard feature in the release planner in early 2023. I updated the wiki for the launch criteria in the old docs with screenshots. This approach worked very well, and the number of questions and time spent helping teams onboard decreased significantly. I suggested moving the screenshots to the new wiki using screenshots was not recommended in the design guidelines for the Engineering Hub site. We should discuss the best format/design to use on engineering hub. 

### Tasks 
- [ ] Redesign release plan overview page - https://aka.ms/azsdkdocs/release-plans 
- [ ] Create and link to demos that cover Release Planner overview, data plane milestone overview, management plane milestone overview
- [ ] Provide guidance on new initial vs new SDK versions requirements to help teams navigate the release plans until they are customized based on the scenario 
- [ ] Create and link to demo that describes the release plan steps and user personas.  Also, provide a diagram overview to support the demo. 
- [ ] Create example release plans in PPE (previously created examples were deleted when PPE environment had to restored). Link to these examples for user's to explore before creating release plans in PROD for their products.

 

Request from Catalinia based on service partner feedback: @catalinaperalta From: Catalina Peralta [Catalina.Peralta@microsoft.com](mailto:Catalina.Peralta@microsoft.com) Sent: Thursday, January 11, 2024 1:37:59 PM To: Justin Bettencourt [jbettencourt@microsoft.com](mailto:jbettencourt@microsoft.com); Mariana Rios Flores [mariari@microsoft.com](mailto:mariari@microsoft.com); LaDonna Quinn [ladonnaquinn@microsoft.com](mailto:ladonnaquinn@microsoft.com) Cc: Laurent Mazuel [lmazuel@microsoft.com](mailto:lmazuel@microsoft.com) Subject: Release planner feedback

Hi all,

I wanted to reach out with a suggestion that I think will help with Release Planner adoption. I’ve noticed that a few service teams seem to be reluctant to begin working with the release planner and usually their questions are related to what information/commitments will be expected of them once they create one. I think having documentation in engineering hub with a step by step tutorial with screenshots of each of the release plan pages would be helpful since some service partners would like to know beforehand what to expect from the app from start to finish. I have seen the diagram we currently have on the site, but I believe a step-by-step tutorial would be even more intuitive and would show service partners what information the app will request from them. This could additionally be done in a video format if we think that would be easier for some folks to learn how to use the release planner.

Here is a quote I got in email today from the Health Insights team about using the release planner: “Is there a tutorial regarding how to complete/use the planner ?”

It would also be good to emphasize that the app is meant to be used by both PMs and developers since I have found that to also be a point of confusion. Highlighting how this app helps/benefits each team member through the process would be helpful and we can start pointing folks to these specific documentation sections to encourage adoption and improve usage.

Let me know if you have any questions or if I can provide any more information. Thanks, Catalina

ladonnaq commented 2 months ago

Per the Design Team guidance, we should not have screenshots of the Release Planner App in our docs. As an alternative, the release plan page describing the steps in a milestone has been updated to direct to other docs pages for more information on the step. We can also include links to completed examples of release plans in the PPE environment.

Here are examples release plans. I will complete all of them and post links to engineering hub. Blocked by permissions for PPE tables (SDK release milestone namespace). Let engineering know and when resolved will complete task.

Private Preview release plan examples:

Public Preview release plan examples:

GA release plan examples:

ladonnaq commented 2 months ago

TODOs: Update release plans once permissions are fixed in PPE for table related to SDK namespace drop-down box. Private Preview release plan examples:

Public Preview release plan examples:

GA release plan examples:

Request engineering to mark all other release plans as abandoned.