Publish templates to azure samples browser

[jongio]

Let's get the templates published here:

https://docs.microsoft.com/en-us/samples/browse/

We need to add necessary yaml header to READMEs and the azure-samples publisher account to azure-dev

[rajeshkamal5050]

Since its a P2 and also, we have the templates gallery site https://aka.ms/awesome-azd/

Moving it to backlog for now.

[savannahostrowski]

This is a dupe of https://github.com/Azure/azure-dev/issues/425. @jongio which do you want to leave open?

[jongio]

two diff imo. This one is "get them out there". #425 is work with docs team to make azd samples standout in the browser with a blue check.

[rajeshkamal5050]

How can we onboard our samples to Learn?

Understanding you have a repo in Azure-Samples org, we need to ensure that the ingestion process is aware of your repo. To do this, we need to complete this onboarding form: https://forms.office.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR17IcoC-CnxGgErwh2l4_cBUNENaVE5FUk1CQ0kwTlo0QkVZUVhCUThXRC4u

What is the process for external contribution on Learn Code Samples today?

As it stands, our external contribution is though GitHub. We do not offer another modality for community publishing on samples at this time. https://review.learn.microsoft.com/en-us/help/contribute/samples/concepts/basics?branch=main#how-can-customers-outside-microsoft-contribute

[savannahostrowski]

@rajeshkamal5050 This should probably go into 0.7 or 0.8 milestone.

[weikanglim]

Onboarding docs are available here: https://review.learn.microsoft.com/en-us/help/contribute/samples/process/onboarding?branch=main#supported-metadata-fields-for-readmemd

[weikanglim]

@savannahostrowski

We need to provide a less than 150-word description that shows up on each sample's card in the gallery.

Highlighted:

Actual gallery link: https://learn.microsoft.com/en-us/samples/browse/?expanded=dotnet%2Cazure

Do you know what we should highlight in these 150 words? I currently have the following for csharp-cosmos-sql:

C# ToDo application that uses Azure Developer CLI (azd) to get you up and running on Azure quickly, with Cosmos SQL API for storage.

I think the description needs to be:

1. Referencing azd in some fashion
2. Differentiated per sample (list the sample feature)
3. Ideally, the template can be reused across samples for consistency.

Azure Developer CLI would show up as a language, so perhaps it might not need to be mentioned in the description. Another alternative I have (1 word over):

ToDo application built, deployed, and monitored with Azure Developer CLI (azd). React.js for Web app, C# for API, Azure Cosmos DB SQL API for storage.

Do you have ideas?

[weikanglim]

Had a new idea:

The title will look something like:

ToDo Application with a C# API and Azure SQL Database

Which already states all the important things about the sample.

I think a standard description that ties into azd, like:

Complete ToDo application built, deployed, and monitored with Azure Developer CLI (azd).

would suffice.

[savannahostrowski]

Do we have to make the title "ToDo" at all? I've been thinking that we might want to reframe the templates to be more about the scenario that they enable. For instance, with the ToDo templates, we are really looking at a web app written in C# using Azure SQL Database. Most users won't necessarily care about the ToDo part and will rip that source code out in favour of their own code. That said, I worry that by promoting the ToDo part too heavily, some users might not think that the template is relevant to them.

That said, could we do something like "Web application with a C# API and Azure SQL Database"? Or is that too generic?

cc: @austinauth for any additional thoughts here (because we talked about this extensively for awesome-azd)

[Austinauth]

@savannahostrowski

A few thoughts:

Re: Calling out service names in the title/description The official Microsoft sample site is fairly restrictive around how a user can discover new templates. You cannot filter by things like service or framework, and only two metadata tags are surfaced on the card itself. So while, "Web application with a C# API and Azure SQL Database" is slightly generic, I think its important to highlight the services in the title or the short description like you have.

Re: Including ToDo in the name I'm still split on this. ToDo isn't really a use case, but I do think it helps affirm that this is a simple application you can conceptualize. As opposed to something more esoteric like some of the examples I've seen: Django SQL Driver or Collision. That being said, we should be good removing it from the title as long as its in the description.

Re: My initial thoughts on naming & use cases These are technically tutorials, but I like how Docker consistently starts their tutorial name with a verb. IMO it makes everything seem more approachable. For us that could look something like this: Deploy a C# web application with Azure SQL Database

Another interesting example is AWS's Solution Library. While its not easy to find a sample by a particular service, they do a pretty good job of enabling discovery by a particular use case or vertical.

[weikanglim]

@savannahostrowski @Austinauth

Thanks for the good callout. One thing to consider here is that by default, the sample metadata will use the first Markdown heading (H1) as the title, which we have "ToDo application" in the title. Our options are here to either override it, or maybe we should make the "scenario" apparent in the description?

To simplify things, here's all the templates below and the required information we need to fill. We need to come up with specific wording for the Title (displayed in the top of the card), and 150-word Description (display in the body of the card):

Template	Title	Description
todo-csharp-cosmos-sql	ToDo Application with a C# API and Azure Cosmos DB SQL API
todo-csharp-sql	ToDo Application with a C# API and Azure SQL Database
todo-csharp-sql-swa-func	ToDo Application with a C# API and Azure SQL DB on Static Web Apps and Functions
todo-java-mongo	ToDo Application with a Java API and Azure Cosmos DB API for MongoDB on Azure App Service
todo-java-mongo-aca	ToDo Application with a Java API and Azure Cosmos DB API for MongoDB on Azure Container Apps
todo-nodejs-mongo	ToDo Application with a Node.js API and Azure Cosmos DB API for MongoDB on Azure App Service
todo-nodejs-mongo	ToDo Application with a Node.js API and Azure Cosmos DB API for MongoDB on Azure App Service (Terraform)
todo-nodejs-mongo-aca	ToDo Application with a Node.js API and Azure Cosmos DB API for MongoDB on Azure Container Apps
todo-nodejs-mongo-swa-func	ToDo Application with a Node.js API and Azure Cosmos DB API for MongoDB on Static Web Apps and Functions
todo-python-mongo	ToDo Application with a Python API and Azure Cosmos DB API for MongoDB on Azure App Service
todo-python-mongo	ToDo Application with a Python API and Azure Cosmos DB API for MongoDB on Azure App Service (Terraform)
todo-python-mongo-aca	ToDo Application with a Python API and Azure Cosmos DB API for MongoDB on Azure Container Apps
todo-python-mongo-swa-func	ToDo Application with a Python API and Azure Cosmos DB API for MongoDB on Static Web Apps and Functions

Card for reference:

[savannahostrowski]

@gkulin has offered to help get these titles and descriptions tee'd up!

[gkulin]

We need to provide a less than 150-word description that shows up on each sample's card in the gallery.

@weikanglim Do you mean 150 characters? Based on the descriptions you suggested, I think that's what you meant. But as I am looking through the gallery, I am coming across quite a few descriptions that are more than 150 characters (but not by much, I think the longest I saw was 167). Where did you get that 150 limit from?

[gkulin]

re: Wei's chart with the info we need to fill.

I went with Savannah's suggestion of not having "ToDo" in the title since that isn't really (most of the time) relevant to the user

One thing to note is that the descriptions are essentially the title but in more words.

Wei had the idea of a standard description that ties into azd which I think might work well. So, the standard description I would suggest:

A complete ToDo list web app using Azure Developer CLI (azd) to build, deploy, and monitor

Template	Title	Description
todo-csharp-cosmos-sql	Web Application with a C# API and Azure Cosmos DB SQL API	A complete ToDo app with C# API and Azure Cosmos DB SQL API for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-csharp-sql	Web Application with a C# API and Azure SQL Database	A complete ToDo app with C# API and Azure SQL database for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-csharp-sql-swa-func	Web Application with a C# API and Azure SQL DB on Static Web Apps and Functions	A complete ToDo app with C# isolated Azure Functions for the API and Azure SQL database for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-java-mongo	Web Application with a Java API and Azure Cosmos DB API for MongoDB on Azure App Service	A complete ToDo app with Java API and Azure Cosmos for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-java-mongo-aca	Web Application with a Java API and Azure Cosmos DB API for MongoDB on Azure Container Apps	A complete ToDo app on Azure Container Apps with Java API and Azure Cosmos API for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-nodejs-mongo	Web Application with a Node.js API and Azure Cosmos DB API for MongoDB on Azure App Service	A complete ToDo app on Azure App Service with Java API and Azure Cosmos API for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-nodejs-mongo-terraform	Web Application with a Node.js API and Azure Cosmos DB API for MongoDB on Azure App Service (Terraform)	A complete ToDo app on Azure App Service with Java API and Azure Cosmos API for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-nodejs-mongo-aca	Web Application with a Node.js API and Azure Cosmos DB API for MongoDB on Azure Container Apps	Complete ToDo app on Azure Container Apps with Node.js API and Azure Cosmos API for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-nodejs-mongo-swa-func	Web Application with a Node.js API and Azure Cosmos DB API for MongoDB on Static Web Apps and Functions	A complete ToDo app with Node.js API and Azure Cosmos API for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-python-mongo	Web Application with a Python API and Azure Cosmos DB API for MongoDB on Azure App Service	A complete ToDo app with Python FastAPI and Azure Cosmos API for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-python-mongo-terraform	Web Application with a Python API and Azure Cosmos DB API for MongoDB on Azure App Service (Terraform)	A complete ToDo app with Python FastAPI and Azure Cosmos API for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-python-mongo-aca	Web Application with a Python API and Azure Cosmos DB API for MongoDB on Azure Container Apps	A complete ToDo app with Python FastAPI and Azure Cosmos API for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor
todo-python-mongo-swa-func	Web Application with a Python API and Azure Cosmos DB API for MongoDB on Static Web Apps and Functions	A complete ToDo app with Python FastAPI and Azure Cosmos API for MongoDB for storage. Uses Azure Developer CLI (azd) to build, deploy, and monitor

[weikanglim]

@gkulin Thanks for looking through it.

I did mean 150 characters, not words 😆. The specification here mentioned no more than 150. On the cards, I do notice some truncation at ~160

[weikanglim]

Looks like we still need:

1. Merge templates from staging -> master
2. Submit the onboarding form for each template
3. Wait for them to publish and verify what it looks like on the review site

[weikanglim]

Submitted onboarding requests for each template

Should see the changes in staging tomorrow.

[rajeshkamal5050]

Completed as part of #425