To grossly paraphrase US Supreme Court Justice Potter Stewart: Good documentation is like obscenity -- you know it when you see it even though you may not know why it's good. You may not know the techniques employed by an artist that cause you to appreciate a painting. You just know you like it.
That's exactly what the DNN Docs Project started doing in our kickoff meeting last week. We can't just throw a lot of content at you and expect it will be good. We need to understand why some documentation projects succeed while others fail. We can then use those lessons to analyze the shortcomings of the current system and build a stronger one going forward. I'll talk more about that in just a moment.
First I want to introduce you to the initial group of dedicated individuals who will help guide and implement DNN's documentation strategy.
Members
Initially, the group is deliberately small so that we can work efficiently and get to a point where more of the community can start participating. However, most, if not all of the names should already be familiar to you. In addition to myself, there is:
- Peter Donker
- David Poindexter
- Patrick Ryan
- Ash Prasad
- Clint Patterson
- Francisco Pérez Andrés
If you get a chance, please thank them for the work they're doing on your behalf.
We've had numerous offers to help with the project. We appreciate your energy and willingness to contribute. We will definitely be knocking on your door soon.
Learning From the Best
Creating effective documentation isn't a new problem. Sure, DNN's needs are going to be unique to the needs of our community but we can learn a lot by looking at how other successful platforms have solved their documentation dilemmas.
I'd like to draw your attention to two such examples. They offer some insight into the choices a team makes based on their content and user base, as well as the trade-offs those choices require. Keep in mind, these are examples of just the API documentation for these services. While our initial focus is on developer documentation, we will be building out/improving a comprehensive set of documentation for all users of DNN.
Stripe API Documentation
This payment processor has taken the ecommerce world by storm due to its simplicity, aesthetic, and I would argue, the strength of its documentation.
Stripe API Documentation
There's a lot to like in these docs. I don't know if they were the first to pioneer this type of 3-column format, but they certainly made the approach popular.
In the first column - the left column - you'll find the table of contents, allowing for quick topic-based navigation. The contents are broken into broad sections to make it easier to drill-down to a specific topic area.
The second, or middle column contains the meat of the documenation - the explanations, definitions, and tables of properties and values.
Most striking, though, is the third column, on the right. This contains actual code examples and API responses. It has the familiar black background of a code editor and leverages syntax highlighting. This immediately makes developers (the intended audience) feel more at home.
The beauty of this approach is that the example code is tied to the content in the second column. So, as you scroll through the documentation, the examples scroll with you. This way the examples are always in sync with the topic being discussed.
Finally, because Stripe has many different SDK's in multiple programming languages, the tabs at the top of the right column allow you to switch between them, so you can focus solely on samples in the language of your choice.
What you may not notice when using their documentation is not only do the examples change when you change language, but certain parts of the content (column two) change as well. I've highlighted those changes between Node and Go in the images below
It's a great trick. More importantly, it allows them to have a single document that acts as if it was custom built for the chosen language. It is potentially easier to keep content in sync between languages, since those differences all appear in the same section of the source file.
Stripe's API docs are all contained in a single HTML page. Clicking a topic in column one will navigate you to a bookmark on the page and update the URL with the appropriate hash.
Since Stripe's documentation is small-ish, they can take this single-page approach and put all their content into a single file. This enables lightning fast navigation, table of content topics in column one being highlighted as they scroll into view in column two, and readers able to use the browser's built-in "find-on-page" search functionality to quickly search the docs. This latter benefit may not be the best UX, but developers should be quite familiar with using Find in a browser.
Stripe's approach has been wildly successful and emulated elsewhere. However, it isn't suitable for all applications. Very large documenation projects, for instance, are simply too large to fit on a single page. File size and conceptual constraints necessitate they be be split into different physical or dynamically generated pages. This, of course, requires implementation of more sophisticated search functionality and may affect site performance.
Let's take a look at a larger developer documentation project and see how they handle the complexities that come with it.
GitHub Developer Documentation
GitHub Developer Docs
GitHub uses a two-column approach with the main content area in column one while the table of contents is in column two, to the right. Each link in column two will take you to a separate page.
For the most part, each page in the docs is substantive enough to warrant further internal navigation. You'll find this at the start of each topic, in column one. Each of these links will jump to a bookmark on the page. A downside of GitHub's implementation is there is no easy way to jump back to the navigation section at the top of the page. Nor can you see the table of contents once it scrolls out of view. The Bootstrap docs do a better job of this by having the table of contents scroll with the user.
Like Stripe, GitHub uses syntax highlighted code blocks. Since this is focused on their REST API, they really only have to support one "language" - cURL. However, you will also find a second style of code block used to identify HTTP responses and general code-related content.
GitHub does still have to support multiple programming languages. They've chosen to deal with them separately as part of their separate SDKs. Those docs are placed in the Libraries part of their docs. This approach allows developers to focus on their language implementation. However, it can create user orientation issues (where do I find the docs I need) as well as potential issues with docs or concepts in one section being out of sync with another since they are authored in separate files.
You're probably way ahead of me on this, but one way GitHub could resolve this issue is to be more like MSDN, with inline code blocks that have tabbed interfaces for each language.
Of course, because GitHub has chosen to break up their content across multiple pages, they also require a search component that can search across all those files. This adds complexity and development time to an implementation.
So, you can start to see some of the tradeoffs that are required to handle documentation projects of different sizes. This has only been a cursory comparison. There is so much more we could dive into including how content is organized and presented on a macro level, small but helpful UX like permalinks on each section/topic, how to handle orientation and route finding for different types of users, switching between different versions of the API, and much more.
DNN's Docs and Next Steps
Neither Stripe nor GitHub are perfect, but they do provide insights we can use as we formulate a strategy for DNN's documentation.
The user-base for DNN's documentation is quite diverse. Even focusing on just developer documentation, our users speak multiple languages, program in multiple languages and have different skill levels, needs and expectations. Additionally, we need to provide a system that makes it easy for community members to contribute as well as fix and maintain the documentation so it remains accurate and up-to-date.
These are complicated issues, but the investment of time we put in now will pay dividends in the future. Currently the team is meeting weekly to hash all of this out. In addition to analysis and requirements gathering, we're already beginning to experiment with tooling, layout, and functionality to better understand the benefits and disadvantages of various approaches--and it's been less than a week since the project kickoff.
What Can You Do Today?
You can help guide our work. We're still gathering requirements for the project. Since we're building the documentation for you, we can't do it without your input and feedback. So, for this week... Do you have an example of what you consider to be excellent API or technical documentation? Is it a different approach you think merits consideration for DNN? Please let me know in the comments.