Products

Solutions

Learn More

Partners

Community

Blog

About

New Community Website

Ordinarily, you'd be at the right spot, but we've recently launched a brand new community website... For the community, by the community.

Yay... Take Me to the Community!

The Community Blog is a personal opinion of community members and by no means the official standpoint of DNN Corp or DNN Platform. This is a place to express personal thoughts about DNNPlatform, the community and its ecosystem. Do you have useful information that you would like to share with the DNN Community in a featured article or blog? If so, please contact .

The use of the Community Blog is covered by our Community Blog Guidelines - please read before commenting or posting.


DNN Docs Preview is Live

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 todayRemember, better documentation leads to a better DNN and that's good for all ofo us. 

Comments

David Poindexter
Fantastic article Kelly - kudos to the entire team! It is so nice to already be seeing and processing more community contributions!
David Poindexter Saturday, April 6, 2019 1:13 AM (link)
Clint Patterson
Yes, I agree ... all good stuff here! Thanks for your leadership and contributing your time, wisdom, and skills to the DNN Docs team and DNN Community at large.
Clint Patterson Monday, April 8, 2019 5:48 AM (link)

Comment Form

Only registered users may post comments.

NewsArchives


Aderson Oliveira (22)
Alec Whittington (11)
Alessandra Davies (3)
Alex Shirley (10)
Andrew Hoefling (3)
Andrew Nurse (30)
Andy Tryba (1)
Anthony Glenwright (5)
Antonio Chagoury (28)
Ash Prasad (37)
Ben Schmidt (1)
Benjamin Hermann (25)
Benoit Sarton (9)
Beth Firebaugh (12)
Bill Walker (36)
Bob Kruger (5)
Bogdan Litescu (1)
Brian Dukes (2)
Brice Snow (1)
Bruce Chapman (20)
Bryan Andrews (1)
cathal connolly (55)
Charles Nurse (163)
Chris Hammond (213)
Chris Paterra (55)
Clint Patterson (108)
Cuong Dang (21)
Daniel Bartholomew (2)
Daniel Mettler (181)
Daniel Valadas (48)
Dave Buckner (2)
David Poindexter (12)
David Rodriguez (3)
Dennis Shiao (1)
Doug Howell (11)
Erik van Ballegoij (30)
Ernst Peter Tamminga (80)
Francisco Perez Andres (17)
Geoff Barlow (12)
George Alatrash (12)
Gifford Watkins (3)
Gilles Le Pigocher (3)
Ian Robinson (7)
Israel Martinez (17)
Jan Blomquist (2)
Jan Jonas (3)
Jaspreet Bhatia (1)
Jenni Merrifield (6)
Joe Brinkman (274)
John Mitchell (1)
Jon Henning (14)
Jonathan Sheely (4)
Jordan Coopersmith (1)
Joseph Craig (2)
Kan Ma (1)
Keivan Beigi (3)
Kelly Ford (4)
Ken Grierson (10)
Kevin Schreiner (6)
Leigh Pointer (31)
Lorraine Young (60)
Malik Khan (1)
Matt Rutledge (2)
Matthias Schlomann (16)
Mauricio Márquez (5)
Michael Doxsey (7)
Michael Tobisch (3)
Michael Washington (202)
Miguel Gatmaytan (3)
Mike Horton (19)
Mitchel Sellers (40)
Nathan Rover (3)
Navin V Nagiah (14)
Néstor Sánchez (31)
Nik Kalyani (14)
Oliver Hine (1)
Patricio F. Salinas (1)
Patrick Ryan (1)
Peter Donker (54)
Philip Beadle (135)
Philipp Becker (4)
Richard Dumas (22)
Robert J Collins (5)
Roger Selwyn (8)
Ruben Lopez (1)
Ryan Martinez (1)
Sacha Trauwaen (1)
Salar Golestanian (4)
Sanjay Mehrotra (9)
Scott McCulloch (1)
Scott S (11)
Scott Wilkinson (3)
Scott Willhite (97)
Sebastian Leupold (80)
Shaun Walker (237)
Shawn Mehaffie (17)
Stefan Cullmann (12)
Stefan Kamphuis (12)
Steve Fabian (31)
Steven Fisher (1)
Timo Breumelhof (24)
Tony Henrich (3)
Torsten Weggen (3)
Tycho de Waard (4)
Vicenç Masanas (27)
Vincent Nguyen (3)
Vitaly Kozadayev (6)
Will Morgenweck (40)
Will Strohl (180)
William Severance (5)
What is Liquid Content?
Find Out
What is Liquid Content?
Find Out
What is Liquid Content?
Find Out