Earlier, I blogged about the Dynamics 365 Business Central user assistance model and what we expect you to do about it. In this blog post, I’ll talk more about the Learn More content that we publish on the Docs.microsoft.com site, how we collaborate on delivering it, the tools and processes we use, and how you might be able to adopt some of our best practices.
The purpose of the docs
As I mentioned in the earlier blog post, we have three layers of user assistance where the context-sensitive links to Learn more play an important part by providing context and links to additional information. In other words, this is not really product Help in the classic sense where the product Help is intended to answer all questions in daily use of the product. There is nothing wrong with that type of Help and, believe me, I’ve written lots of it. But when we started work on what is now Dynamics 365 Business Central, we decided to tackle user assistance in a different way. Business Central is cloud-first, and that changes how we think about the functionality and the user experience.
So the docs are still docs, but the content is not an online version of a user manual. The product itself does far more of the job of helping people figure out how to complete tasks compared to way back when I started working on software in the ’90s.
In other words, the docs are there as a supplement, not a prerequisite. This applies to the business functionality content more than to the developer and IT-Pro content, but we work on both sets of content in roughly the same way: In MarkDown files in GitHub repositories where we collaborate with program managers (PMs) and engineers to develop the content.
Let’s take a look at how that works in the daily lives of the Business Central team.
How content is created and published
All content on the docs.microsoft.com site is created and published in the same way:
- Person A creates a MarkDown file, adds content, and then submits it to a GitHub repository.
The new file is automatically processed by our build system for the docs.microsoft site and rendered on an internal staging server where we can preview the content before it’s published.
- If Person A is a technical writer like me, they will then send a link to the internal staging server to the PM and/or software engineer that they are collaborating with for technical review. The reviewers will submit a pull request with changes that Person A will then merge into the relevant branch.
- If Person A is a PM or engineer, they will ask a writer to review the changes before the pull request is merged into the master branch. The writer usually makes light edits as part of the pull request and, if needed, more substantial edits in a separate iteration.
- After a couple of iterations, the content is ready to be published as part of the weekly refresh (we publish every single Monday, in case you didn’t know), unless it has to wait until the next major update for Business Central.
We have subbranches for individual features that are then merged into the relevant branch when it’s ready to be published as part of the monthly service update or the major update in April or October. Keeping track of what must be published when is not always easy, but we have two main tracks: Bug fixes and new features for the next major release.
The build system that the docs.microsoft.com site uses is essentially a bunch of scripts, but the main engine is the DocFx tool that you can also use. For more information, see https://dotnet.github.io/docfx/. We’re privileged by the fact that Microsoft is a pretty large company, so I don’t know much about the build system because it’s managed by a completely different team in a completely different part of the company in a completely different country.
Working in MarkDown files
I’m a technical writer, so I do heavy-duty work in MarkDown files in my local clone of the different repositories on my laptop. The PMs that I work with mainly do more lightweight work, so they tend to just make changes right in the browser at the equivalent of https://github.com/MicrosoftDocs/dynamics365smb-docs/tree/master/business-central. But let’s take a closer look at the tools I use. These examples are based on our internal, private repo that you can’t access, but the same principles apply to the public repos.
First of all, I use Visual Studio Code with a couple of nifty extensions, not least the Docs Authoring Pack, which I highly recommend. In general, jump over and take a look at what some of my colleagues are publishing in the Docs Contributor Guide!
Then I use GitHub Desktop to get updates from GitHub and then push my changes back to GitHub – my teammates are working in the same repositories as I am, and we synchronize changes several times a day to make sure we aren’t undoing each other’s work. It’s one of the drawbacks of having moved to GitHub: If you’re not careful with your commits, you can accidentally overwrite changes made by someone else, so pay attention to what is being merged in your pull requests!
This is what it looks like when I start work after someone else has submitted changes:
Once I pull those changes down, GitHub merges them into my clone so that I am ready to work on the latest version. In case you’re wondering, the screenshot is from the private repo that we use internally, but it’s the same mechanism in all repos.
Here’s what I see when I then open the folder with the Business Central docs in Visual Studio Code:
The green squiggly lines are validation errors thrown by the Docs Authoring Pack. In this case they’re shown because it wants a blank line after each heading. When I first wrote this article I was using the Atom markdown authoring tool, which doesn’t insist on blank lines after headings. Visual Studio code does, hence the squiggles.
After I’ve made my changes, I use GitHub Desktop to commit them.
Note the blue button at the bottom of the window – this is GitHub telling me what I’m about to do. in this case, I’m pushing to the master branch, which is the basis for content ready to go live. If I had intended this change to get published later, then I would have to stop here and commit my change to another branch.
In this case, it’s a small update that I want to apply to the already released content, so I’m committing to the master branch. After I commit the changes, I have to push the commit to GitHub.
This step is about pushing my change from my clone up into the online GitHub repository. The terminology can be confusing at first, but the trick is to think of the clone as being on your computer and the “real” repository being up in the cloud. At least, that’s done the trick for me.
As mentioned, having moved our docs to GitHub repos has enabled collaboration scenarios that we have dreamed about for many years. You as our partners, can extend and customize our docs easily because the public GitHub repo is always there for you to pick up from. No more native tooling because there is a world of open source tools readily available. And you can submit GitHub Issues or pull requests if there is something you want to change in the docs. This transparency and flexibility works very well for the way that our product, Dynamics 365 Business Central, is extended and customized, don’t you think?
We welcome your contributions, even when it might seem that we don’t, such as when it takes a while before we process your feedback. We’re a small team with a lot of work to do, and we don’t mean to appear like we don’t appreciate your feedback. And that goes across our portfolio – application and developer content for Business Central, application and developer content for Dynamics NAV, and the emerging application and developer content for Dynamics GP.
For Dynamics NAV and Dynamics GP, our own support folks are actively contributing to the docs already, and you can as well. However, we only accept contributions to the English (US) source at this point in time.
For Business Central, we very much also welcome contributions, but as you know, the product is still evolving, and that means that docs are as well. For example, if you are frustrated that you can’t read about how to develop a specific solution in the new development environment, then that’s probably because the tooling isn’t available yet. Don’t be frustrated. Instead, rejoice in the fact that you are part of the collective journey that we are on in a true partnership to evolve Business Central.
So if you want to contribute to the content, just find the relevant place in the docs, notice the file name in the URL (it’s the last bit of the URL, such as contributor-guide), then find the right repo in GitHub ( business functionality is at https://github.com/MicrosoftDocs/dynamics365smb-docs, developer content is at https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb), find the file, and hit the Edit button. You will then get a notification like this:
You’ll need a GitHub account to do this, of course, but that’s easy to get. In your fork of the repo, you then make the changes that you want to make, and you end up submitting a pull request to our repo. For more information, see the GitHub docs.
We share our tools and processes with you, so join us, and collaborate on the content. We welcome you! For more information, see Extend, Customize, and Collaborate on the Help for Dynamics 365 Business Central.
Content in agile development projects
Some of you have moved to agile development methodologies, but you’re struggling to find out how you can deliver Help for your apps and solutions. Depending on whether you have in-house technical writers, or if you depend on external service providers to generate the docs for you, you’ll find different solutions to this problem, I am certain.
If you’re looking for inspiration, I have written several examples on LinkedIn about how to use agile methodologies to help you structure work and produce the content that you need.
For more information, see my post on LinkedIn. And keep up the good work that you’re already doing!
PS: This blog post was first published on the Communities blog in December 2018 but has been migrated and updated here on the Dynamics 365 blog.