My impressions of software documentation
This page summarizes my impressions of various software documentation. It is heavy on stereotypes because I want to give my high level views and not have to go back to specific examples. I realize the lack of examples will make this page unhelpful to readers, but hopefully some people can get something out of this page.
I usually find Google documentation confusing and unhelpful. The documentation doesn’t usually cover the thing I’m looking for, or the emphasis is off, or something like that.
By “the emphasis is off” I mean something like that the page is going into great detail about something I don’t care about or don’t know why I should care about, instead of the thing I came to the page for.
In addition, Google’s documentation tends to make heavy use of JavaScript so I find them slow to load, which is annoying especially since I’m trying to do something.
GNU project
I find the GNU project’s documentation usually unhelpful. The emphasis is off. I can’t usually find the thing I am looking for. The pages seem to try to exhaustively list out options and flags rather than being more “tutorial based” or “questions based”.
I also dislike the tree structure of the documentation. The “nodes” are too small in my opinion, and the different nodes don’t link to each other. Rather, there is just a single sequence of nodes organized along the main tree.
Vim
I have come to really like Vim’s help pages. They are written
clearly. I like using the :help command to navigate the
pages inside Vim. Vim’s documentation is also wiki-like as it
links between various parts of the documentation. CTRL-]
and CTRL-T allow me to follow links and go back.
As Vim’s documentation is just local text files, they are fast to load.
I find the punctuation in the documentation occasionally “off” (e.g. comma splices).
Man pages
I find man pages generally helpful, but mostly because I don’t expect much from them. If I just want to know what a specific flag does, I will read the man page, but otherwise I will usually search online. This means I don’t run into situations where I am specifically frustrated at a man page.
MediaWiki
I have found MediaWiki documentation clear enough, and I like that the pages link to each other.
Amazon
I usually find Amazon documentation unhelpful, but I have limited experience here.
Amazon’s website seems to use a lot of JavaScript, making the pages slow to load. I also don’t like the persistent navigation side bar on the page.
Facebook’s documentation is slow because of all the JavaScript. I also have not found it helpful. It does not take time to explain features that have been removed. It does not explain background terminology (e.g. the different API types) clearly enough, making me have to search through a bunch of Stack Overflow answers and blog posts.
Python
I find Python’s official documentation and some library documentation (e.g. requests or BeautifulSoup) to be pretty good, and refer to them often.
I think Python’s documentation does a good job of giving minimal examples. These minimal examples are simple enough that they don’t require a lot of working memory to understand.
I still refer a lot to Stack Overflow answers while writing Python though, so that suggests the documentation is perhaps not comprehensive enough.
A lot of the other documentation on this page is about specific tools, but Python documentation is about a language and its APIs. I wonder if that makes it easier to produce.
MySQL
I like the MySQL official documentation, although most of the time I supplement it with answers on Stack Overflow and other sources, so in that sense I don’t have “high expectations” from the official documentation.
Various repos on GitHub
I find popular GitHub repositories to have pretty good documentation, especially for quickly getting started. The readme files being on the repo’s front page probably helps with making a “good first impression”.
I also really like the trend of including screenshots and animated GIFs in the readme files.