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:
- 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).
- 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.