Microsoft has always been viewed as a developer friendly company. Almost every product they build is extensible and includes in-depth documentation. All of this documentation is maintained in the Microsoft Developer Network (MSDN), which is one of the premiere developer documentation centers in the world.
Since DNN was first created, thousands of pages of documentation and hundreds of videos have been created. Much of this documentation is available at various locations on DNNSoftware.com and in a few external sites. Documentation is available as help files, pdfs, wiki articles, blog posts, videos and PowerPoint slide-decks. Unfortunately, it is not always easy to find the information you are looking for, and when you do find it, it is not always clear if the documentation is up to date.
Finding the right tool
Last fall we decided that it was time to start consolidating all of our documentation efforts in one location. As part of this effort we looked at many different documentation systems to find one that could handle the wide variety of documentation formats we need to support. We identified the following key features:
- multiple output formats (e.g. HTML, PDF, ePub)
- multiple device formats (e.g. desktop, tablet, phone)
- support multiple products (platform and Evoq) and product versions
- allow community feedback and contribution
- open content format (no commercial software needed to create documents)
- extensible and templatable
After looking at many different options, we finally settled on the Sphinx Documentation Generator. Sphinx is an open source system created by the Python community for their own documentation efforts, and is built using reStructuredText markup format and the Jinja template engine.
Although Sphinx started as a Python documentation tool, it includes support for documenting many different programming languages and has since spread to other development communities. This tool was also recently chosen by the ASP.NET team for documenting ASP.NET Core.
the Documentation Center
Having chosen our documentation system, we started creating new documents to populate the documentation center. With so much existing documentation it would be easy to get overwhelmed with the shear magnitude of effort required to convert everything to the new format and move it to the documentation center. Some of the existing documentation is outdated and won’t be moved. Additionally, there are some portions of the system that were undocumented.
For the initial release of the documentation center we have focused on getting a framework in place with some baseline documentation. The documentation center includes articles to help you get started with DNN, some initial how-to documents, some high-level conceptual information, and links to existing documentation. For the immediate future, the documentation center will serve as a hub while we continue the migration effort.
I am proud to announce that the DNN Documentation Center is now live. The documentation center is intended to serve all of our users; whether you are a developer, administrators or designer, there is documentation available for you.
We still have a lot of work left to accomplish this year and we could use your help. You can find the documentation source documents on GitHub. If you find a problem with the documentation, enter an issue in the GitHub issue tracker or submit a Pull Request. With your help we can accelerate conversion of the existing documentation and improve the overall quality of the DNN and EVOQ documentation.