DNN Docs Project Update - April 2019

A lot of time has passed since my last official blog update on the DNN Documentation Project. However, we have been hard at work, meeting weekly to hash out ideas and solve problems. I wanted to let you know where the project stands currently. First, you can skip this article and check it out now at https://dnndocs.com. We are still in a "preview" phase, since there is a lot of work left to do, but it is fully functional and combines content from the current docs center as well as up-to-date API documentation. On with the update.

Settling On A Toolset

Since the project’s inception, we have worked with multiple tools, trying to determine the most appropriate for our needs. That doesn’t mean the best tool, it means the one that best meets the requirements of the project.

After trialing several static site generators as well as a custom DNN-based solution, we chose Microsoft’s documentation tool DocFX. Its primary benefit for us is its ability to read a Visual Studio project, extract the XML comments, and generate documentation — similar to the old Sandcastle tool, but a bit better. It generates static HTML and enables us to write articles in plain text, using Markdown. This means we can combine the DNN documentation and the API documentation into one site. Further, it provides additional customization and extensibility options that offer enough flexibility to implement custom features and styling.

Debuting at DNN Summit 2019

Ironically, the documentation for DocFX isn’t very good. So, it took quite some time, a lot of trial-and-error and a fair bit of GitHub/Twitter stalking of the DocFX team members to understand how to make it do what we wanted.

We were finally able to put together what we considered a minimally acceptable first effort and debuted the DNN Docs Preview at this year’s DNN Summit in Denver — the culmination of nearly a year’s worth of effort. The team worked really hard to get the docs site into this initial form.

At that time, the site contained the content from the existing documentation center, converted from the original DITA format. It included API documentation from the DNN source code. It demonstrated the ability to integrate with Jenkins, building from the dnndocs GitHub repo as well as the Dnn.Platform repo. Finally, it also included searching, filtering, and our ability to adjust the style and layout.

The Community Steps Up

Since the Summit, we haven’t let down. In fact, we’ve redoubled our efforts and have had some excellent contributions from the community.

Brian Dukes helped school us on effective git techniques and workflows to help handle community contributions, fixed a bunch of outdated URL’s, and just recently added a new article to the docs on Module Injection Filters.

Will Strohl has helped correct and clarify several topics and has recently released a series of videos on how to contribute to the DNN Docs Project.

Oliver Hine, Daniel Valadas, Tycho de Waard, and Andrew Birks have all jumped in and fixed items they’ve run across. Plus, because the project is pulling XML documentation from the DNN Platform project, every change that developers make to the in-code documentation automatically updates the documentation in the DNN Docs API section.

The increased community involvement has further motivated the team to do more to improve the docs and the contribution process.

New Milestones Reached

Finally, I want to discuss a few internal milestones that we’ve reached for the project.

Better Searching

Initially, we relied on the built-in searching mechanism (lunr) of DocFX. While this worked, since it is a client-based searching mechanism, it required the user to download a hefty, multi-megabyte index file on the first search. This was clearly unacceptable for production use.

We reached out to the good people at Algolia and they are now indexing the DNN Docs site and providing the search services. This is the same service used by Bootstrap, React, Vue, and many other popular documentation projects. Team members Patrick Ryan and David Poindexter worked to integrate the Algolia search into the site. The results are pretty awesome: super-quick (1 or 2 millisecond) search times, full-text searching, and indexing of articles as well as API docs — all presented in a user-friendly results pane.

Automatic Build and Deployment

Just recently, we’ve completed another milestone. The DNN Docs project is now being automatically built and deployed. We use Jenkins to detect changes in the GitHub repo, automatically build (also pulling the most recent state of the Dnn.Platform repo), and deploy to a secure website behind a CDN. What this translates into is that anytime a Pull Request is merged into the Docs Repo, a new build is automatically kicked off and live on the DNN Docs site usually in just over 5 minutes.

Better Navigation

At DNN Summit, the navigation of dnndocs.com was functional but less than ideal for its initial release. We now have implemented a tree view navigation for easier browsing of content.

API Documentation Decoration

Peter Donker has successfully demonstrated our ability to enhance the API documentation without us having to inject a lot of extra comments into the source code. Now we are able to create additional explanatory text and code examples for any part of the source code in Dnn.Platform, without having to touch the source code. See the example for DotNetNuke.Entities.Modules.Settings for an example. The Remarks section has several paragraphs and source code examples detailing how to use the Settings class. This was added as part of the documentation project and is not contained in the XML comments in the source code.

Recognizing Contributors

As I’ve said from the beginning, the documentation project will not succeed without community involvement and contributions. Our central mission has been to make contributions easy. To that end, we have created a system that is integrated with GitHub so you can add content and correct mistakes with pull requests. If you just want to make suggestions or report bugs, you can submit a GitHub issue.

We continually monitor for new issues and pull requests on our #dnndocs channel on Slack and in email. We strive to process those issues and pull requests as quickly as possible. Once merged, the changes are automatically pushed live to the site. This ensures that the content you see on the site is the most up-to-date content available.

As part of our commitment to the community, we are proud to announce that we are now able to recognize your contributions within the documentation itself. With the tireless work of David Poindexter, we are now integrated with the GitHub API and are able to pull contributor data directly into the docs. On the home page is a live list of the top contributors to the project. On each internal page (outside of the API docs) the authors and contributors to that page are displayed just under the title at the very top. As part of this change, we've also added the last update date for the page and an estimated time to read.

There’s More to Come

We are continually energized by your contributions, suggestions, and help. We want to emphasize that these are YOUR docs. Their success is in your hands. So, whenever you run across a problem or figure out a solution, think about adding it to the documentation site. If you can create a good example of how to use a class or method in the DNN API, click the “Improve This Doc” button on the page in question. If you’re a site admin, content manager or designer help us out by filling in and updating the Administrator, Content Manager, or Designer sections of the docs. If you’re a coder, help us by filling in missing documentation to the Dnn.Platform XML comments (one great place to start is the DotNetNuke.Entities.Portals.PortalSettings). 

We are far from finished improving the docs and the contribution processes, but we want you to start contributing new articles or changes starting today. Remember, better documentation leads to a better DNN and that's good for all ofo us.