diff --git a/.github/agents/blogs-docs.agent.md b/.github/agents/blogs-docs.agent.md new file mode 100644 index 0000000000..2b7ac06045 --- /dev/null +++ b/.github/agents/blogs-docs.agent.md @@ -0,0 +1,45 @@ +--- +name: Blog-Docs-Writer +description: Specialized agent for creating new documentation, editing existing documentation, and writing blog posts for new features. +tools: ['read', 'search', 'edit'] +--- + +You are a documentation specialist designed to write technical documentation, edit technical documentation, and summarize new features for blog blurbs or standalone blog posts. If you are editing or creating documentation, you create a pull request at the end of the creation process. Do not create a pull request until the content has been approved. + +1. **First determine** + - Does the user want to create docs, edit docs, create a blog blurb, a standalone blog, or some combination of the above? These are the only actions you can do. + +2. **Next ask for** + - Does the user have specifications, related documentation, or other content that can be used for reference? + - If there are no specifications, can the user describe the feature and the necessary elements for the document to be created? + - If creating new docs, which type of document (how-to, tutorial, conceptual, quickstart, overview) does the user want to create? + - Are there ideal examples of this kind of document within the repo? + +3. Create a work plan, including outline. Do not proceed until the user has approved. Take into account the following general structures: + + **Blog blurb** + - What is the feature and why should I care + - Screenshots + - Link to learn more in documentation + + **Standalone blog** + - an expanded version of the blog blurb + - include scenarios for when to use this feature and how it can be used in conjunction with other parts of the product + - include a next steps section for users to get started + + **New document** + - Use relative links (e.g., `docs/CONTRIBUTING.md`) instead of absolute URLs for files within the repository + - Use Microsoft style guide rules when writing + - Use templates in the ~/.github/agents/templates folder for the selected type. + +4. Now create the requested documents + + **File Types You Work With:** + - markdown (.md) + - images (.png) - all images must be hosted in the media/doc-file-name folder and embedded using the following example syntax: :::image type="content" source="media\add-source-sample-data-enhanced\add-sample-data.png" alt-text="A screenshot of selecting Sample data to add to an existing eventstream."::: + - table of contents files of type .yml + - text output for blog posts + + **Pull request** + - If you are creating new documentation or updating existing, after the document is done then you must create a pull request (PR) under the user's fork against the main branch of the microsoft fork + - If you are creating a blog, return the content as text. Do not create a PR. diff --git a/.github/agents/templates/concept.md b/.github/agents/templates/concept.md new file mode 100644 index 0000000000..a3258fa13d --- /dev/null +++ b/.github/agents/templates/concept.md @@ -0,0 +1,102 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: concept-article #Don't change. +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# [noun phrase] concept(s) + +or + +# [noun] overview + + + +[Introduce and explain the purpose of the article.] + + + +## Prerequisites + + + +## [Main idea] + +[Describe a main idea.] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/agents/templates/how-to.md b/.github/agents/templates/how-to.md new file mode 100644 index 0000000000..7185b3434d --- /dev/null +++ b/.github/agents/templates/how-to.md @@ -0,0 +1,125 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: how-to #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# "[verb] * [noun]" + + + +[Introduce and explain the purpose of the article.] + + + +## Prerequisites + + + +## "[verb] * [noun]" + +[Introduce the procedure.] + +1. Procedure step +1. Procedure step +1. Procedure step + + + +## Clean up resources + + + +## Next step -or- Related content + +> [!div class="nextstepaction"] +> [Next sequential article title](link.md) + +-or- + +* [Related article title](link.md) +* [Related article title](link.md) +* [Related article title](link.md) + + + + diff --git a/.github/agents/templates/overview.md b/.github/agents/templates/overview.md new file mode 100644 index 0000000000..670f773e76 --- /dev/null +++ b/.github/agents/templates/overview.md @@ -0,0 +1,80 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: overview #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# What is [product or service]? + + + +[Introduce and explain the purpose of the article.] + + + +## [Feature section] + +[Introduce a section that describes a feature.] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/agents/templates/quickstart.md b/.github/agents/templates/quickstart.md new file mode 100644 index 0000000000..da5187134b --- /dev/null +++ b/.github/agents/templates/quickstart.md @@ -0,0 +1,188 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: quickstart #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Quickstart: [verb] * [noun] + + + +[Introduce and explain the purpose of the article.] + + + +If you don't have a service subscription, create a free +trial account . . . + + + +## Prerequisites + + + +## Open [Cloud Shell, Azure CLI, or PowerShell] + + + +## [verb] * [noun] + +[Introduce a task and its role in completing the process.] + + + +1. Procedure step +1. Procedure step +1. Procedure step + + + +## Clean up resources + + + +## Next step -or- Related content + +> [!div class="nextstepaction"] +> [Next sequential article title](link.md) + +-or- + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/agents/templates/tutorial.md b/.github/agents/templates/tutorial.md new file mode 100644 index 0000000000..d5fbf84bad --- /dev/null +++ b/.github/agents/templates/tutorial.md @@ -0,0 +1,174 @@ +--- +title: Page title has the greatest effect on search +description: The meta-description is not crawled for search rank, but is displayed in the browser. +author: +ms.author: +ms.service: +ms.topic: tutorial +ms.custom: mvc +ms.date: 11/16/2017 + +--- + + + + +# Tutorial: + + +Introductory paragraph. + + +In this tutorial, you learn how to: + +> [!div class="checklist"] +> * All tutorials include a list summarizing the steps to completion +> * Each of these bullet points align to a key H2 +> * Use these green checkboxes in a tutorial + + +If you don't have a subscription, create a free trial account... + + + + +## Prerequisites + +- First prerequisite +- Second prerequisite +- Third prerequisite + + +## Sign in to + +Sign in to the [ portal](url). + + +## Procedure 1 + + + +Include a sentence or two to explain only what the reader needs to do to finish the +procedure. + +1. Step one of the procedure +1. Step two of the procedure +1. Step three of the procedure + :::image type="content" border="true" source="media/contribute-how-to-mvc-tutorial/browser.png" alt-text="Browser."::: + + +1. Step four of the procedure + +## Procedure 2 + +Include a sentence or two to explain only what the reader needs to do to finish the procedure. + +1. Step one of the procedure +1. Step two of the procedure +1. Step three of the procedure + +## Procedure 3 + +Include a sentence or two to explain only what the reader needs to do to finish the +procedure. + + +Here is an example of a code block for Java: + + ```java + cluster = Cluster.build(new File("src/remote.yaml")).create(); + ... + client = cluster.connect(); + ``` + +or a code block for Azure CLI: + + ```azurecli-interactive + az vm create --resource-group myResourceGroup --name myVM --image win2016datacenter --admin-username azureuser --admin-password + ``` +or a code block for Azure PowerShell: + + ```azurepowershell-interactive + New-AzureRmContainerGroup -ResourceGroupName myResourceGroup -Name mycontainer -Image mcr.microsoft.com/windows/servercore/iis:nanoserver -OsType Windows -IpAddressType Public + ``` + +## Clean up resources + +If you're not going to continue to use this application, delete + with the following steps: + +1. From the left-hand menu... +2. ...click Delete, enter...and then click Delete + + + +## Next steps + +Advance to the next article to learn how to create... +> [!div class="nextstepaction"] +> [Next steps button](contribute-get-started-mvc.md) + +