DNN Community Blog

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 Features and Progress

I was recently reminded of the need for good consistent communication by community member Abdelhadi Bukres. He correctly pointed out that it has been too long since I last updated you on the status of the DNN Docs project. Too often we get in the weeds of our projects and day-to-day tasks that we forget just how much time has passed.

Lest you think that the DNN Docs project is moribund because I haven't blogged, let me correct that notion as quickly as possible :) We have been meeting weekly since the project's inception and working diligently moving the project forward.

As I've tried to explain in my previous post on what makes good documentation, there are myriad ingredients that go into successful help projects. In addition to the content, there are technical aspects such as tooling, hosting, build tools, versioning, etc. Of course, we need to think about the different types of users who will be using the docs - what their intent is and how to structure their journey so they can accomplish their goal efficiently. Of equal importance, we need to create a system that welcomes contributions from the community while maintaining a common voice and consistent presentation to the end user. Needless to say, it's a tall order.

I've been remiss in sharing our progress over the past few weeks, so I'd like to follow-up my What Makes Good Documentation post with a look at what we've identified as a feature set for the docs project as well as some of the decisions the list has prompted.

Note that we didn't create this in isolation. In addition to analyzing multiple documentation projects, we solicted and received suggestions and feedback from the community. I should also note that the list is not exhaustive, nor will everything on the list make it into the project and some items may be implemented later in the project's life. However, it has been very helpful in informing our choice of formats and tooling.

Working Feature Set

In no particular order...

  • Language-Specific Syntax Highlighting: The developer documentation will rely heavily on code snippets. Simply using a monospace font isn't enough. Comprehension is aided when that code is color-coded in accordance with the programming language involved.
  • Multiple Programming Language Support (CSS, HTML, ASP.NET, C#, VB.NET, JS, etc.): Some topics may need to combine both HTML, CSS, and Javascript along with server-side code in the same space. In some cases, it may be desirable to show different approaches using the same language (for example, vanilla Javascript versus ES6).
  • Ability to use code blocks as well as inline code We will obviously need to accommodate both long and short code snippets.
  • File-Based: This allows topics to be assigned and managed individually in an atomic fashion. Translators can simply create a new file for their language. It also makes it much easier to manage content similar to the way source code versioning is managed.
  • "Githubbable": As an open source project, it is essential that the community can contribute to the Docs project in a way similar to how they contribute to the DNN project. This will provide the ability for users to contribute via Pull Requests, clone the project for local development, and even fork the project for their own uses.
  • Localizable: Ability to be translated into other spoken languages
  • Embeddable Images/Video: Some things can only be conveyed visually.
  • Contributor Credit: Since this is a community proejct, we should provide a means to recognize individuals for their efforts.
  • URL Control: The ability to structure the address for each topic to indicate the topic, the spoken language, the DNN version and, to the extent possible, the topic's context in the content hierarchy. Ideally, the URL structure should be understandable and consistent enough so you can, for instance, edit the URL to switch versions.
  • Internal Linking to topics within the documentation
  • Quick Linking: We want to provide an easy way for a user to copy a link to the page so it can be quickly shared in other venues like Facebook and Twitter as well as the DNN Forums.
  • Hover Definitions: Also called "drops". Since we cannot assume a user will read a series of topics in sequence, hover definitions will enable the content to use terminology for clarity and conciseness, while allowing users unfamiliar with the term to click or hover over that word to see a definition or explanation.
  • Includes: We want to avoid repeating code/content  as much as possible, so the ability to define re-usable components or content blocks will reduce maintenance and encourage consistency.
  • SEO: While we aren't necessarily interested in "hitting #1 on Google", the intent here is to enable users to ask questions of Google and see the answers in the results. This is similar to when you search for "javascript array splice" on Google, you'll get the MDN (Mozilla Developer Network) documentation for the splice method on the array prototype.
  • Search: This is critical to users finding the information they need as efficiently as possible. Ideally we would like type-ahead functionality and smart searching.

Some Conclusions

The above feature list is not exhaustive. However, it has influenced a number of choices we've made for the project thus far:

  • The DNN Docs project will be a GitHub repository. In addition to making the content public, most potential contributors already have a GitHub account. Modifications can be made via Pull Requests. The repository can be cloned to user's environments as well as forked. GitHub's API also provides a flexible platform on which we can build additional features such as crediting contributors.
  • Markdown Format: Topics will be individual markdown files. As with GitHub, Markdown is a syntax that potential contributors will be familiar with. Its limited syntax is easy to learn for users who are unfamiliar. It provides structure to the content without mingling styling. Additionally, it is plain text, making it readable by humans and portable across systems. There are also multiple libraries that can convert the format to other formats like HTML and even PDF's. We are aware there are some trade-offs we'll have to make with Markdown. The very simplicity that makes it so easy to use could limit our ability to provide some features.
  • Static Site Generation: The irony of using a static site to document a content management system is not lost on us. While we could program a custom system in DNN, time spent programming is time not spent creating documentation. After the documentation is complete, the site will only be updated when new versions of DNN are released or modifications need to be made. There is no need to dynamically generate pages as a user requests them. Static site generators produce HTML files. As a result, they are performant, search engine friendly, and can be hosted virtually anywhere. While the docs may ultimately be hosted inside a DNN site, that is not our priority at this time.

Choosing A Tool

Given the above feature set we determined we need a static site generator that was flexible enough to allow us to build features in the future if necessary. Many generators are geared toward specific types of content like blogs. Some are geared specifically for documentation. There are even some services designed to create and host documentation. While these tools and systems enable us to get started quickly, they typically are not as flexible as we would like and/or conflict with other goals we have for the project (like portability and community involvement).  

Choosing tools can quickly devolve into religious warfare among tech people. No tool provides every feature, nor does it meet every requirement and everyone has good reasons why their favorite is the best. So the team has endeavored to be pragmatic in its approach -- to find tools that provide enough flexibility to meet most of our needs but also don't require a huge investment of time. Here, our choice of Markdown is already paying dividends. It means the content will be portable to other tools or systems if required.

Our evaluation has settled on two open source contenders: Metalsmith and React Static. We haven't made a final call on either generator. Metalsmith is essentially a Javascript build process with plugins. It's very flexible, but would require more up-front effort to create a system for our project. We are currently evaluating React Static. As its name implies, it provides nearly all the flexibility of a react application, while producing static HTML. Given the growing community of react developers within the DNN community and usage of react in DNN itself, we should have plenty of people who can customize the tool or create plugins going forward.

Moving Forward

Even though we are a small team, every week, we make more progress. Currently, we are working on two parallel tracks: 

  1. Creating the content architecture: Identify the content areas/topics that should be in the documentation. This includes topics in the existing documentation as well as missing areas. We are working to structure this into a coherent framework (think table of contents).
  2. Testing our assumptions and conclusions by actually creating content. We are creating sample content that will eventually be in the documentation. The content is crafted to allow us to test the limits of our chosen set of tools, exercising as many facets in the feature set list as possible. It will also enable us to better understand the processes we need to establish for community contribution guidelines, technical review, etc.

I hope this provides you with a fairly complete picture of our progress and process. We are working hard to get to a point where we can open up the process to contributors. If you are interested in contributing to the project as a writer or reviewer, please myself or Clint Patterson know. Of course, I look forward to reading your contributions in the comments below.  


Comments

Ernst Peter Tamminga
Great blog. It shows that you have been working on a workable solution.
Is it possible to include wiki content of other repositories, e.g. a wiki of a DNN module?
Ernst Peter Tamminga Tuesday, May 22, 2018 6:08 PM (link)
Kelly Ford
Hi Ernst Peter,

I'm not sure if you are asking about including documentation for DNN Modules in the DNN Docs project or if you are referring to including wiki-formatted content, generally. So, let me try and answer both... Other core community projects could certainly have their docs included in this system. Of course, our initial focus is on documenting the core DNN project. Using GitHub will allow people to submit issues and pull requests to modify content or suggest/request additional content be added. As for the formatting... we are using Markdown, so all docs would need to be written as such. Now, if you're talking about pulling data from GitHub repo wikis, that is possible with react-static because it enables us to pull "dynamic" information from API's during the build process. So we could theoretically use the GitHub API to retrieve this information.
Kelly Ford Tuesday, May 22, 2018 6:22 PM (link)
Ernst Peter Tamminga
@Kelly: Thank you for your quick and extensive answer. I was refering to wiki content in other GitHub repositories, most notably DNN modules and other types of DNN releated projects.
Ernst Peter Tamminga Tuesday, May 22, 2018 6:52 PM (link)
Abdu Bukres
Thanks for the info. I have checked out React Static at https://react-static.js.org. I assume their documentation is baded on React Static. I looked at the documentation. Looks good. I notice a couple of things. There was no built-in search. I am OK with using Google. Google is usually better than the local search features. The left navigation hierarchy is a single level. I hope it works more like a treeview to support topic categories and multiple levels of subcategories. I hope creating content with it doesn't require any kind of knowledge of React. Some content authors are not that technical.

I looked at Metalsmith at http://www.metalsmith.io. The couldn't find what looks like documentation. All I saw is a simple page with text. No content navigation. My first impression is it's too simplistic, until I see real more sophistation documentation example written with it.

Abdu Bukres Wednesday, May 23, 2018 6:11 AM (link)
Kelly Ford
@Abdu Bukres: Yes, the react-static docs are built with react-static. The important thing to keep in mind is that it is a _tool_ for generating static sites, and not a help authoring system specifically. So what they build with it may be different from what we build. In fact, they built their docs on react-static only after we selected them. We haven't settled on a layout yet. We've investigated 2 and three-column layouts. We are also testing the system to see how flexible we can make the table of contents/navigation since DNN's docs require much more content than you'll typically find. A number of projects have used Metalsmith to build their docs. We haven't chosen them at this time because it would require more scaffolding work.

Regarding search, we've been working with the fine folks at Algolia. They host searching for some of the biggest projects like Bootstrap, React, Vue, and Stripe. I've used them on a number of projects and am really happy with the results.

I should note that choosing react-static does not in ANY way imply that contributors will need any React knowledge. They will simply contribute markdown (.md) files to the project. You can think of react-static as the build system. Layouts/templates are created in react-static, but the content is contained and authored in markdown files.
Kelly Ford Wednesday, May 23, 2018 1:32 PM (link)

Comment Form

Only registered users may post comments.

NewsArchives


Aderson Oliveira (18)
Alec Whittington (11)
Alex Shirley (10)
Andrew Hoefling (2)
Andrew Nurse (30)
Andy Tryba (1)
Anthony Glenwright (5)
Antonio Chagoury (28)
Ash Prasad (35)
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 (212)
Chris Paterra (55)
Clinton Patterson (71)
Cuong Dang (21)
Daniel Bartholomew (2)
Daniel Mettler (164)
Daniel Valadas (1)
Dave Buckner (2)
David Poindexter (9)
David Rodriguez (3)
Dennis Shiao (1)
Doug Howell (11)
Erik van Ballegoij (30)
Ernst Peter Tamminga (77)
Francisco Perez Andres (6)
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 (3)
Ken Grierson (10)
Kevin Schreiner (6)
Leigh Pointer (31)
Lorraine Young (60)
Malik Khan (1)
Matthias Schlomann (15)
Mauricio Márquez (5)
Michael Doxsey (7)
Michael Tobisch (3)
Michael Washington (202)
Miguel Gatmaytan (3)
Mike Horton (19)
Mitchel Sellers (31)
Nathan Rover (3)
Navin V Nagiah (14)
Néstor Sánchez (31)
Nik Kalyani (14)
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 (2)
Vicenç Masanas (27)
Vincent Nguyen (3)
Vitaly Kozadayev (6)
Will Morgenweck (40)
Will Strohl (169)
William Severance (5)

Content Layout

Subscribe to DNN Digest

Subscribe to DNN Digest

DNN Digest is our monthly email newsletter. It highlights news and content from around the DNN ecosystem, such as new modules and themes, messages from leadership, blog posts and notable tweets. Keep your finger on the pulse of the ecosystem by subscribing.  

What is Liquid Content?
Find Out
What is Liquid Content?
Find Out
What is Liquid Content?
Find Out