For years I've heard complaints about the state of DNN's developer documentation. It's time we solve it once and for all. I'm going to be spearheading the initiative but first allow me to share how I got to this point.
As you may know, DNN 9.2 includes a significant new addition: Prompt - a fast, friendly, extensible command-line interface for the Platform. It was voted the best open source contribution at DNN-Connect 2017.
What you may not know is that I'm the one who created it (with critical contributions from Peter Donker, David Poindexter, and Clint Patterson). I mention this not to be self-congratulatory, but as an introduction for those who may not know me (this is my first DNN blog post) and to provide some context.
Prompt is my first community contribution. However, it won't be my last because just a few days ago, I was forwarded this compliment:
"Not sure who did it, but the help and doc for PROMPT is a great job, the first useful help in DNN ever!"
That's a pretty remarkable comment and made me grin from ear-to-ear. Documentation is usually a thankless job. The only feedback you get is usually negative.
You see, I'm a firm believer that good documentation is a critical component to the success of any application. It's why I spent so much time on Prompt's help system, choosing to write the documentation in parallel with my development rather than after the fact.
So here I was patting myself on the back... but one phrase in that comment kept gnawing at me like Poe's Telltale Heart...
"...the first useful help in DNN ever!"
Unfortunately, this isn't the first complaint a community member has voiced about DNN's docs. I've been developing for DNN since v.1.08 and my personal experience has been one of frustration with the documentation or lack thereof.
I know I'm not alone in this experience. Developers can spend hours trolling through forum posts, superficial wiki entries and tangentially related blog posts before resorting to digging into the source code to find answers to their questions.
Let me be clear. Doing documentation well is a large undertaking that takes a lot of work. The larger the project, the more difficult the task. Many efforts have been made over the years to improve the situation in DNN. Progress has been made and the recent Documentation Center is a good step in the right direction. But there is so much more to be done.
Documentation is Crucial to DNN's Success
Let's face facts. If we want the platform to thrive, we need greater adoption by developers. The only way that's going to happen is if someone finally takes the bull by the horns and creates documentation that makes it much easier for new and experienced DNN developers to create innovative solutions.
So, I'm happy to announce I'll be spearheading a new community effort to take DNN's documentation to the next level. I realize I'm kind of sticking my neck out here. It was not more than a couple paragraphs ago I was talking about what a hard and thankless task documentation can be. However, I truly believe that excellent documentation is critical to DNN's success. I hope you agree. In fact, I want you to do more than agree. I'm going to need your help.
This week I'll be initiating the effort by meeting with a (deliberately) small group of individuals with a long history in the community. Our goal is to determine the best approach to tackling this issue. I've got a lot of ideas about the "ideal" documentation and I'm sure you do as well. In the coming weeks I'll post about our progress and solicit feedback from you. I can guarantee one thing. Successful documentation is a community effort.
Contributions are the life-blood of a healthy open source project. We plan to create a framework that enables you to contribute for the benefit of yourself and the community -- much as I contributed Prompt. If I'm the only one working on the project, it will fail but together we can build community-driven documentation that benefits everyone, attracts new people, and grows the ecosystem. I hope you'll join me in the journey. Watch this space...