This post has come about from a couple really bad experiences with documentation this week, and what I found frustrating in those experiences.
While providing complete information in docs, it should be done in a simple enough way that the user has basic building blocks. Additionally, the (entire!) docs should be reproducable.
Here are the failures I’ve delt with this week.
First, Material Design Lite. MDL is a nice, simple framework for Material-themed sites, but it lacks documentation for basic building blocks. It turns out that in MDL the grid system is key to a lot of styling. For example, the Cards component requires either the grid or custom CSS to be any usable. However, the docs seem to give the impression that the CSS you see for the demo content is for demonstration purposes, not that the cards don’t really function without it. The Grid component section of the docs also fails to impress this upon you. For contrast, the Bootstrap docs have the first post-install section dedicated to the Layout, without having the navbar and footer stuff taking up most of the page. Additionally, there is nothing similar to Bootstrap’s
.container building block which allows for extremely simple. I had to go digging through the source code of the MDL sample templates just to find out how to do very basic positioning of content, which is very sad. This also led me to a second discovery – MDL has a lot of styling classes that are undocumented. Things like
mdl-color--(color) for background,
mdl-color-text--(color)-(size) are completely undocumented. I feel like I ran across them in a footnote in the docs at one point, but I was unable to find it again. This is also a huge issue for usability since the Material Design’s spec has very specific color palettes and shadows, complete with custom scales. As mentioned, these features exist, but you can’t find anything reasonable about them, which severely limits the ability to make a website intuitively.
In summary, documentation is important, and usability is as important as completeness. It doesn’t matter if your project has documentation when I am unable to get a working base installation and/or are missing a sizeable chunk of the basic functionality needed to use a project.