Products

Solutions

Learn More

Partners

Community

Blog

About

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.


What Makes Good Documentation?

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 Screenshot.png
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

Stripe Dev Docs Node.png

Stripe Dev Docs Go.png

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 2.png
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.

GitHub Developer Docs 3.png

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.

MSDN Docs Tabbed Interface.png

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.

GitHub Developer Docs 4.png

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.

Comments

Patrick Ryan
Very thorough and well done Kelly.
Patrick Ryan Tuesday, April 3, 2018 5:38 PM (link)
Tony Henrich
I like Microsoft's new documentation site: docs.microsoft.com. Here's why and I want DNN's new documentation to consider the points I will bring up:

- Navigation on the left and main content in the middle. Pretty standard
- date at the top showing when it was created or last updated. Good to know how fresh the content is
- A list of the contributors. Give some credit to people who contributed
- Code is color coded, can be highligted and is a in a box and there's a copy to clipboard button
- Discussion at the bottom of each topic. People can give feedback or ask questions about the topic at hand. Right there with the topic documentation.
- An option to send feedback
- An option to edit the content
- An option to share the content
- A light and dark theme. I like dark themes in everything I use. More comfortable for my eyes
- Icons for reading or adding comments in different lines. Great way to give feedback right there where the content is
- An option to download the content as pdf. This seems to download the whole documentation. For people who want to read the content offline on their e-readers.
- An option to print. This seems to be missing on their site. My workaround would be to print from the pdf. I can decide which pages to print.
Tony Henrich Wednesday, April 4, 2018 4:52 AM (link)
Kelly Ford
Thanks for the thoughtful response Tony. We have looked at and are drawing inspiration from Microsoft's new docs site. You brought up a couple of items we hadn't considered, though. Thank you!
Kelly Ford Wednesday, April 4, 2018 1:51 PM (link)
Alvaro Torres
I'm sure you already know this tool, but just in case ...https://readthedocs.org
Alvaro Torres Thursday, April 5, 2018 5:51 PM (link)
Kelly Ford
Thanks for the input Alvaro. Yep. We are aware of it.
Kelly Ford Thursday, April 5, 2018 6:28 PM (link)
Sid Childers
I too like the docs.microsoft.com layout. I would also add that Github source examples would be helpful too. As such, a description of the class or method, how it interacts with the rest of the DNN ecosystem, and an example or two of how to implement said method in C#/VB.
Sid Childers Monday, April 9, 2018 5:46 PM (link)

Comment Form

Only registered users may post comments.

NewsArchives


Aderson Oliveira (22)
Alec Whittington (11)
Alessandra Davies (3)
Alex Shirley (10)
Andrew Hoefling (3)
Andrew Nurse (30)
Andy Tryba (1)
Anthony Glenwright (5)
Antonio Chagoury (28)
Ash Prasad (37)
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)
Clint Patterson (100)
Cuong Dang (21)
Daniel Bartholomew (2)
Daniel Mettler (165)
Daniel Valadas (21)
Dave Buckner (2)
David Poindexter (12)
David Rodriguez (3)
Dennis Shiao (1)
Doug Howell (11)
Erik van Ballegoij (30)
Ernst Peter Tamminga (79)
Francisco Perez Andres (12)
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)
Matt Rutledge (1)
Matthias Schlomann (16)
Mauricio Márquez (5)
Michael Doxsey (7)
Michael Tobisch (3)
Michael Washington (202)
Miguel Gatmaytan (3)
Mike Horton (19)
Mitchel Sellers (35)
Nathan Rover (3)
Navin V Nagiah (14)
Néstor Sánchez (31)
Nik Kalyani (14)
Oliver Hine (1)
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 (3)
Tycho de Waard (3)
Vicenç Masanas (27)
Vincent Nguyen (3)
Vitaly Kozadayev (6)
Will Morgenweck (40)
Will Strohl (172)
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