We all spend a good portion of time reading documentation? As employees, techies, owners of techie doohickies, as human beings... We're usually hoping to get in, find what we need quickly, and get on with life. Unfortunately, some docs leave us expecting something more. After finding a few recently, I felt like taking a few minutes to reflect on what makes some sites great and some.. not.
The sections of the page don't really stand out. Many of the explanations sound like they're taken straight from a comment in the code, rather than someone trying to explain something to a visitor of the site. That may be the case, since the footer includes "Generated with Ruby-doc Rdoc Generator 0.42.0.".
It's better than nothing, I guess. At least there's a search function.
Microsoft's MSDN docs are generally very helpful. Not every document is a homerun, but many of them are clear and informative... they've really improved over the years. The page on the generic List<T> class includes really thorough examples with explanations about each part, remarks on performance, and a description of every available method and property.
Like MDN, I like that there's a decent amount of whitespace and comfortable line heights, a nice font, a muted palette with a pleasant selection of colors, which all add up to being easy on the eyes. The floating table of contents helps prevent getting lost in a long document. The example code is complete and very thoroughly explained, and can be copied / pasted directly into Visual Studio or .NET Fiddle without much fuss. The text sounds like someone giving instructions, not someone commenting their code.
In general, most Microsoft docs are pretty good.
What is it with Ruby? For such a friendly language, there's a number of sites like RubyDoc.info that seem to just generate docs from the source code. Ouch. There's some good info here, but nothing easy on the eyes. Look at that scrollbar on the right... at least 50 pages of info on each construct but no table of contents. There's a navigation bar on the left, loaded in an iframe, which somehow messes up printing so that if I wanted to print everything on strings (maybe to a PDF?) I only get the first page and a half of info.
Check out the reference to
Symbol#id2name in the second example. Why make the visitor dig for things instead of linking to the appropriate doc? The "Thread" page has a nice explanation and some examples, but better styling to improve readability would go far.
DigitalOcean is just awesome, not only because the docs on how to use their own services (of which I've been a happy customer for several years with this blog) are so helpful, but because they host tutorials and docs from the community (some of which may even be written by their own employees) that explain things not directly related to their services, like setting up SSH keys on Ubuntu or securing Apache with Let's Encrypt.
I like that the guides are always laid out well and obviously proofread. The sidebar is clean, with a helpful table of contents. The color palette is muted and the font family (proxima-nova), size (16), and height (1.5) are easy on the eyes. There's adequate whitespace although I wouldn't mind a horizontal rule between sections, preceding each header... personal preference. The comments area on the bottom is nice too, and seems to see a lot of engagement from visitors.
I use this device at home and really like it, and the site itself is pretty clean. Unfortunately, a portion of their documentation consists of links to YouTube videos. I'm not sure why someone decides to go this route, as creating videos is more costly and time-consuming, tougher to update as the hardware/software changes, and (most importantly) impossible for a search engine to crawl and index.
I'd much rather have web pages with clear steps and some decent images over high quality videos, so I can send a friend to a particular section of a page and easily find it by searching Google later. Videos make for a nice presentation at a trade show, or for use as advertising, but not as permanent documentation.
To be fair, they have quite a bit of documentation that is text-based and searchable, but the whole section on setting up a new device consists of embedded YouTube videos again. Personally, I can skim text faster than the couple minutes it takes to watch the video.
Ghost Blog 😃
The team behind the Ghost blog engine has a great looking docs site too. Everything is laid out nicely, plenty of breathing room and nice color and font choices. Well-chosen CSS really makes a world of difference.
They've got built-in search, a place for feedback at the bottom, a table-of-contents, a link on every page to GitHub where you can submit fixes... they've got it all!
For the past few years, I've spent quite a bit of time browsing Ericsson's doc site. It's enough to make you cry. If not for Fred Hebert's Learn You Some Erlang site, there'd be a support group for Erlang developers. There might be anyway.
No images, crappy formatting, no search, no comments area, awful table of contents... completely different navigation areas on the left depending on what section of the manual you're looking at (BIFs vs other stuff vs Dialyzer). Okay, I need to get off this site. Bleh.
Nerd Fonts repo 😃
This one's a little different, in the sense that it's just a readme hosted on GitHub. Creating a decent readme within the confines of what GitHub allows can be tricky, especially for large project with a lengthy readme, but Ryan McIntyre did an amazing job with Nerd Fonts. The nice formatting, the table of contents, the font links... that's all manual work, or at least uses an outside tool, since GitHub doesn't generate any of that for you automatically.
Anything in a GitHub wiki 😰
Time to pick on myself. I really like wikis. I even run a personal wiki on DigitalOcean, just to store notes and documentation for myself. The GitHub wiki is a separate repository, and it's actually quite powerful if you access it with Gollum, but unfortunately GitHub completely botches the experience.
Sure, some documentation is just plain ugly and other documentation is great, and with a lot of effort it could look as nice as the NerdFonts readme, but anything in a GitHub wiki is at an immediate disadvantage.
You can't upload an image directly, you don't get an auto-generated table of contents, there's no full text search capability, etc., even though this stuff is possible when using Gollum. I really hope now that Microsoft owns it they'll fix it up a bit... they've already made a number of nice improvements.
Bonus site that redeems Ruby documentation... :)
RubyGems has a ton of easy-to-read guides, involving making and publishing gems, running a gem server, etc. I stumbled on it when I was creating a gem for the first time. Nice font, nice spacing... search and table of contents.
It's easy to read, thorough, and there's even a section to outside resources. I'll be revisiting this one.
My only gripe is the choice of boldface type on the left navigation. IMO, the navigation bar should take backseat to the main content, but here it stands out in a big way. On my blog, I even added a bit of CSS that fades the sidebar out slightly if you're not focused on it.
Got any other great (or hideous) examples of docs? Something you'd be proud to contribute to? Anything you're forced to use but absolutely hate?
Share them below... I'd love to check them out. Especially the hideous ones. ;)