Contribute to Dynamics 365 documentation
You can contribute to Microsoft documentation for Dynamics 365 in two ways. If an article contains incorrect or confusing information, or if you know a good workaround for a recurring issue, you can use the feedback link in the article to let us know.
For most of our documentation, you can also edit an article directly to start a review process.
Provide feedback
On the learn.microsoft.com website, each Learn article offers the opportunity for you to provide feedback. You can choose the Feedback action that's under the article title on the top right or one of the feedback options at the bottom of the article in the Feedback section. Give the article a rating, select the reason for your feedback, and consider leaving a comment. The feedback goes to the article's author and the team that owns the docs.
If an article can't be edited directly, or if you're not comfortable editing, we encourage you to use the feedback mechanism to tell us what you think about the article or the product.
External contributions to Microsoft documentation
The source files for our core content are stored in public GitHub repositories. Anyone can review them and, in many cases, edit them. We welcome your suggestions and corrections, either in the form of direct contributions or as GitHub issues to report a bug or ask a question. We can only accept feedback and contributions to the source content in English.
Most articles have a pencil icon with the tooltip Edit This Document. Select the icon to open the article in GitHub, and then start editing. Get started as a contributor with the Microsoft Learn contributor guide.
If you want to get thorough and contribute new conceptual articles, use the templates at https://github.com/MicrosoftDocs/dynamics365-docs-templates.
Dynamics 365 guidance content
Dynamics 365 guidance content uses the same processes as most documentation on Microsoft Learn. In this section, we call out tools and processes that you can use to help up add to the implementation guidance.
The term guidance content covers the Dynamics 365 implementation guide, descriptions of business processes, new patterns, best practices, and reference architectures. We published the first guidance content in April 2023, and we add updates every two weeks. Browse the guidance hub, and let us know what's great and what's missing.
Some of the guidance content is provided by internal contributors. We encourage subject matter experts throughout the community to help us establish best practices. Read on if you have a best practice or other insight that you think ought to be part of Microsoft Learn.
Why contribute?
We believe the guidance content helps make Dynamics 365 implementation projects run faster. Our partners and customers can use the guidance to prepare for implementation and to skill up in new areas or skill up new staff. Software developers can use the content as a platform to promote their intellectual property or industry expertise.
But we at Microsoft aren't the only experts on how to implement solutions with Dynamics 365. The community includes people who are experts at various aspects of implementation. Do you have a pattern, a best practice, a configuration, or an integration architecture that works well across several implementations? Consider sharing it here on Microsoft Learn to make the whole community even more productive and efficient in their implementation projects.
We hope to be able to offer rewards or other acknowledgments for contributions eventually. In 2023, we recognize contributors in the articles.
How to contribute
You can find the source files for Microsoft's Dynamics 365 guidance content in a public GitHub repo. You can also edit the articles on the learn.microsoft.com/dynamics365/guidance site as described in the Microsoft Learn contributor guide.
We recommend that you submit corrections the same way you submit a correction to other areas of Microsoft Learn. However, to submit new content, we ask that you upload your Markdown files for new guidance content to a different repo, Dynamics 365 Patterns and Practices. This way, we can make sure that your reference architecture or pattern is reviewed by other subject matter experts. There are different templates to choose from, and if you want to contribute to the business process content, there's a different process altogether.
Templates
Microsoft provides templates in two locations, depending on the type of template:
Markdown templates are in the https://github.com/MicrosoftDocs/dynamics365-docs-templates repo.
The docs-templates folder contains templates for conceptual and navigational articles.
The /guidance-templates/ folder contains templates for architectures, solution ideas, and patterns. These templates are the same ones that are used across Microsoft but have been made specific for Dynamics 365.
Word and PowerPoint templates are in the Dynamics 365 Patterns and Practices repo.
The /templates/business-processes/ folder contains Word templates for the business processes articles. We invite all subject matter experts to help us write them. The folder also contains an Excel file with the list of business processes we have identified. The list will evolve over time.
The /graphics/ folder contains PowerPoint files for each end-to-end scenario, to which you can add your own diagrams.
We'll add more templates and guidance over time. We recommend you follow the repos, or save them with a star, so that you get notified when something changes.
Share your feedback on the https://github.com/microsoft/dynamics365patternspractices/discussions tab in the Dynamics 365 Patterns and Practices repo.
If you don't already have a GitHub account, get started with the Microsoft Learn contributor guide.
Tip
Browse our source files in the https://github.com/MicrosoftDocs/dynamics365-guidance repo. Learn from the way that we structure the different types of articles so that your articles follow the same structure. That way, the review process runs faster.
Architectures
We welcome contributions of architectural guidance, including solution ideas and design patterns. If you have a best practice or reference implementation, submit your proposal either to the Azure team or to us in Dynamics 365.
To contribute new articles to the Dynamics 365 architectural guidance, follow these main steps:
- Fetch the appropriate Markdown templates from the guidance-templates folder in the dynamics365-docs-templates GitHub repo.
- Write your contribution.
- Submit your article as a Markdown file in a pull request in the dynamics365patternspractices repo. The
/submit-architecture/folder is ready to receive your contributions.
Microsoft processes the article and publishes it as part of the Dynamics 365 guidance documentation.
For a general introduction to guidance content at Microsoft, see the Azure Architecture Center. For the contributor guide, see Azure Architecture Center contributions.
The GitHub repo dynamics365-docs-templates contains the following Markdown templates for architectural guidance in the guidance-templates folder:
Generalized architecture pattern: A generalized architecture pattern acts as a core architecture with a common solution that applies to many scenarios. For example, solution ideas can build off an architectural article to provide a lens for a particular industry or partner solution and link to the architecture from each solution idea. The template is based on the Azure Architecture Guide template. Use it for different types of architectures, including reference architectures.
Solution idea: Solution ideas are "small" architectures of Dynamics 365 implementations. They provide brief overviews of solutions with Dynamics 365 and Azure services. Each solution idea contains the following elements:
- An architecture diagram
- A dataflow
- Components, meaning a list of the services used
- Contributor credits
- Links to next steps and related resources, such as related guides and architectures
Sample solution: Sample solutions are example workloads with "medium" architectures. They guide readers through the process of designing solutions for specific problems in Dynamics 365 implementations. Sample solutions provide actionable architecture guidance based on real customer examples. The goal is to shorten customers' learning curve by telling them the story of another customer who had the same journey. They include the sections from the Solution Idea template and add the following sections:
- Alternatives, other services that you can plug into the architecture instead
- Considerations, guidance that maps to our Success by Design framework and, optionally, includes a deployment
Design pattern: Dynamics 365 design patterns address specific challenges in implementations and are based on a specific scenario or best practice. Use this template to capture a business process pattern. Alternatively, use the Word template at dynamics365patternspractices/templates/business-processes.
Business process contributions
The term business process covers a wide range of structured, often sequenced, activities or tasks to achieve a predetermined organizational goal. The term can also refer to the cumulative effects of all steps progressing toward a business goal. Business processes are particular to solutions that include Dynamics 365. We believe this new content type creates a structure that helps customers and partners be better prepared to adopt Dynamics 365. Each business process includes a diagram of a standard business process flow. Sections of the document outline configuration steps and the data entities used in each one. Each step links to the relevant page in the product documentation, and all documents have links to next steps and related resources to help readers along their learning journey.
We structured the business processes in a catalog. The business process catalog is an Excel workbook that we at Microsoft use to organize and prioritize our work on the business process documentation. The format is Excel because it makes it easy to sort and filter the entries. We also believe our partners can use the Excel workbook to organize their onboarding journeys, their implementation projects, and their own business processes.
Download the latest version of the catalog from https://aka.ms/BusinessProcessCatalog.
Note
If you want to contribute to the business processes, register your work before you start to reduce the risk that someone else is working on the same business process. To register your work, submit a GitHub issue at https://github.com/microsoft/dynamics365patternspractices/issues.
What the catalog contains
The catalog defines four levels of content:
End-to-end processes
We've identified 15 end-to-end scenarios. We describe the scenarios in business terms, not in terms of software technology.
For each end-to-end process, the introductory article describes how we think about the end-to-end process. We list the key stakeholders and how Dynamics 365 helps the end-to-end process. We also provide an overview, along with a business process flow diagram, of how the end-to-end process interacts with other end-to-end processes. The introduction lists the prerequisites for implementing a solution to support the end-to-end process.
Business process areas
Each end-to-end scenario covers two or more business process areas. This level is just a way to group the business processes for easier searching and navigation. In most cases, the business process areas are separated by major job functions or departments in an organization. Currently, the catalog defines more than 90 business process areas.
Business processes
The term business process covers a wide range of structured, often sequenced, activities or tasks to achieve a predetermined organizational goal. The term can also refer to the cumulative effects of all steps progressing toward a business goal. Each business process describes a function or process that Dynamics 365 supports. So far, we've identified nearly 700 business processes. Some apply to a single Dynamics 365 app, and the documentation for the app might already describe the process. By collecting all business processes here in the guide, we hope to provide a single entry point with links to relevant product-specific content.
Patterns
In Dynamics 365, patterns are repeatable configurations that support a specific business process. They include the most common use cases, scenarios, and industries. Often, there are many ways to implement Dynamics 365 to meet your business requirements. Our goal with patterns is to provide a baseline for your implementation. We've identified more than 2000 patterns, and we expect that number to grow significantly over time.
Get a further introduction to the business process catalog at About the business process guide.
Submit your contribution
Internally at Microsoft, we're working hard to convert internal notes, years of experience, and various documents into business process guidance. We very much welcome contributions from the community.
There are different templates for submitting contributions based on the type of article. Contributors must choose the right template for the appropriate type of article that they want to contribute to. Templates are available as Word files that are named to explain what kind of article the template is intended for.
Contributor recognition
The Microsoft Learn platform shows both internal and external contributors at the top of each article if they submitted their contribution through GitHub. Some people contribute in other ways, so we add a Contributors section toward the end of the article.
The optional Contributors section lists key contributors with their name and a link to their LinkedIn or other profile if they provided one. The following screenshot is an anonymized version of the Contributors section in an Azure Architecture Center article.
Here's what it looks like in Markdown.
## Contributors
*This article is maintained by Microsoft. It was originally written by the following contributors.*
Principal author:
* [Author's Name](https://www.linkedin.com/in/author-account/) | Author's job title or similar
Other contributors:
* [Contributor's Name](https://www.linkedin.com/in/contributor-account/) | Contributor's job title or similar
* [Contributor's Name](https://www.linkedin.com/in/contributor-account/) | Contributor's job title or similar
Getting listed as a contributor this way is optional. Across Microsoft, we recommend using the Contributors section if external contributors submit new content, such as reference architectures and design patterns, through other means than GitHub.