As of today the AzureBI documentation site is official available. This website is the result of my decision I made a couple of weeks ago: to open source all my community project documentation.
Idea
The idea behind this website is my decision to open source my community project documentation, like the description of the Power BI HierarchySlicer.
There are two major drivers behind this decision:
- I use Disqus as commenting platform for my weblog and automaticly it was also the default commenting system for the documentation. But soon I ran into problems that the same comments we given, mixed comments of either a question or an issue and comments that were outdated as a new version with a fix was already available. To state it simply: I lost control due to the amount of comments.
- The recent changes Microsoft did to their technical documentation at https://docs.microsoft.com made me very happy: completely open sourced and their recently introduced commenting via GitHub issues.
Behind the scenes
Tacking the above drivers into account I decided to do the same: open source it, host in on GitHub and use GitHub issues + workflow for commenting.
To make the transition easier: all my documentation was already created in Markdown so that would be a 'copy-paste' activity.
Searching the Internet, I found DocFX and looking at it: look like this is the same building platform Microsoft is using for their documentation. And a big advantage: it has (simple) search capabilities, options to generate generic navigation structure and creates of every page a table of contents (TOC).
The harder part was to integrate GitHub issues into the generated static documentation website. For that I used some JavaScript code from Microsoft and created a script that injects the GitHub issues as comments. At this moment I only show the first issue and the amount of comments combined with a link to GitHub to see the complete thread.
Also creating new issues is done directly via a link to GitHub and not via my documentation site.
Site overview
Each page has a Feedback section containing one or two sections: Documentation and Product. The last section is only available at pages that directly describes one of my community products.
The comment sections consist of two different tabs: open comments and closed and a link to open a new issue.
The feedback section of the Product tab is linked to the product GitHub repository and shows the current open and closed issues.
At the top left of each page there are two links: Feedback and Edit. The first will scroll down to the Feedback section and the last one will open the document on GitHub.
Future
At this moment the website is loosely coupled to my weblog and the old documentation is still in place. Soon I will start redirecting the old URLs to the new website.
One major (technology) step is not yet in place: renewing the documentation is a manual process of building the documentation and uploading it. But I am going to change this and create a build and release process, so I only have to approve pull request.
After that probably I will update the feedback system to include the complete issue thread and the option to leave your comment directly on the site and removing the 'Open a new issue on GitHub' URL link
So everybody: feel free to comment/create issues and submit PRs.
-JP