Web Developer in Boulder CO The Blog

In the age of Google, the success of a technical product relies on more than just the search-ability of your documentation. If you are successful a community of users will spring up. They will post on forums looking for solutions and others will answer them. The search-ability of these nuggets of information is very important. They will make up the fabric of the experience that a technologist will have with your library, tool or other technology. Let us take a recent experience I had as an example.

I was looking for information on MySQL "views" and could not find anything because Google kept getting confused between the common English word "view" and the technology an SQL "view." To make matters worse, the English word is used in MySQL documentation mixed in with the MySQL feature called a view. Throughout the documentation there is "view a table", "view results", "view a view" and much more. Google does not know if the article is about the feature or the article just contains the English word view a ton. Have I beaten a dead horse? Now this is where I cut Sun Micro-Systems (bought by Oracle) who created MySQL some slack. It's true that MySQL predates Google, but the example stands never the less.

When documenting code you have to remember that a search engine will be the way people research and learn about your technology. In our MySQL example, a "view" as a term is much too generalized. Likewise, using some gibberish name like an infobubble or some other such nonsense does not make anything easier as well. It needs to make sense but also not confuse the search engine. Keep in mind that people tend to shorten the names you may give them, so if the MySQL developers renamed "views" to "sql_views", people might shorten it back to "views." Sometimes you might have to run this risk, but doing that is certainly better than using a ubiquitous term to define the major concepts in your technology.