Google Search is great, or why should your internal documentation be public
Recently, I answered a question on Programmers.SE about documentation tools such as Confluence for the internal documentation of the project. My answer was badly written and I had no enough time or interest to rewrite it correctly, so I removed it. There was, however, one interesting point I want to rant about more in detail.
In my answer, I was telling that the person should chose a documentation tool based on six criteria, including this one:
It should have a search feature which works. Note that there are currently no tools which pass this criteria.
This is, it seems, a broad problem which covers nearly all websites. I'll first explain why search is important, and then rant about the lack of proper search itself.
Documentation search feature should work
The problem with internal documentation is that often, it's never read. Why?
Obviously, because in an open space (and who cares about private offices?), it's easy to shout your question and wait for an answer from your coworkers, rather than make an effort opening the documentation and eventually finding the relevant part of it and read it.
This means that whatever can simplify the workflow (open the documentation, find the relevant part, read it) should be done. Unfortunately, I've seen many teams doing whatever they can to make the workflow rather unbearable.
Open the documentation.
What about having to go to an intranet site with a very explicit URI such as
http://192.168.1.94/sphynx/abby/default, then being requested to enter your user name and your password, given that neither of two correspond to your LDAP account (“Why are you, damn fools, creating an intranet site, since you are not even using the only benefit of an intranet vs. internet app?!”) and should be found on one of your post-its, and when you've finally found it, it appears that it's no longer valid, because of 30-days password expiry policy (“Why are you, damn fools, making your company less safe while annoying everyone?!”) which requires you to call a system administrator to get a new password?Find the relevant part.
Quick UX exercise. Should you use a tree or tags to organize documentation articles? Beep. Those who answered “a tree” are wrong. A tree implies exclusivity: an article can be found in one and one only location. The right answer is “tags”, because it makes it possible to locate the same article following different trains of thought. At a very basic level, imagine a person searching for a way to remove a product. Unfortunately, there is nothing related to “Product removal”, because the author of the article put it in
Deletion\Products. In practice, tree exclusivity becomes particularly harmful in more complex situations than that.Unfortunately, most documentation tools I've seen are encouraging a tree as a primary organizational tool, which impacts very negatively the search experience (and can lead to content duplication, content obsolescence and other ugly things).
Read it.
Imagine that the internal documentation actually answers your question, but is written by a person who should never list writing skills in his CV. I've seen code bases where every comment (99% of comments being useless, by the way) contained errors, misspellings and a mix of French and English (in code bases written by French coders). Are those people able to write an article? If they write one, would it be of any help?
Most content written by IT personnel (including managers) in France is not only completely useless, but also completely unreadable. I don't know why those people are even writing anything, because they are clearly unable to express even elementary ideas.
Efforts can be made to make the documentation a primary candidate for team members looking for help. If we focus specifically on the second step of the workflow, a search feature can make all the difference. Spending ten minutes exploring the tree or browsing through a list of tags is not a fun thing when you have to meet the deadline which, by the way, is in three days. Typing what's on your mind in a text box and run through the first five results looks much more promising.
Ideally, a member of a team should be able to open a web page (which has an explicit, easy to remember URI, such as http://docs.example.com/), express his mind in a text box, and be amazed by a set of particularly relevant results.
But I'm still waiting for a product with a search feature that works
So the search should work.
Except that it doesn't on most websites. Many websites are just completely brain damaged, and should plainly remove their search feature. Some are not brain damaged, but don't work well either. A few have a search feature which works, like Stack Exchange, given that Google still obtains a slightly better relevance when doing a search within a given Stack Exchange site.
I understand why is this like that. Google spent a huge amount of money on their search engine, and it became an excellent product. Other companies can't spend that much money on a search feature within a documentation tool, which means that their search will probably be inferior.
What I don't understand is that there is an obvious solution:
Open your documentation to the public.
And by public, I mean Google. And by Google, I mean your own team.
Two hours ago, I was writing another article. In this article, I wanted to put a link to a recent article talking about roadmaps. And something else. I don't remember what exactly, but I remember that roadmaps were mentioned.
From there, I had a choice. I could:
Search manually the list of articles. This would be two keys to open a new tab, enough keys to open my blog, a click on the list of articles, two keys to open on-page search, a few keys to find “roadmap”, and a click on the article.
Search by querying directly MongoDB. The benefit of this approach is that I can then tell myself that I'm the only one in the world who can do that, being at the same time the developer of the blog engine, the author of the blog and the system administrator of the machines which host the blog app and the corresponding database. Aside this tiny short moment of exuberant pride, this would result in many clicks and keystrokes, as well as a Google search, since I have frankly no idea how should I do a full-text search on a MongoDB collection.
Search with Google. Not surprisingly, “roadmap site:blog.pelicandd.com” yields immediately to the article I need. Thank you, Google.
When writing this article, I was again faced with a problem. I remember writing about trees and tags, but where? Again, “tree site:blog.pelicandd.com” got the first search result right, given that the word “tree” wasn't even mentioned in the title, and wasn't the primary keyword I was thinking about when I was writing the corresponding article (which also means that I would get the tags wrong, missing the tree tag if my articles were tagged for search purposes).
Edit: I'm still amazed by the convenience of Google search. When writing an answer on Programmers.SE, I wanted to put a link to a blog article where I discussed the problem of introducing quality standards in the middle of the project. Since I wasn't remembering the title, I glanced for a few minutes on the list of articles, and then typed in Google “stylecop better site:blog.pelicandd.com”. Magically, it showed the article, exactly the one I was looking for.
Edit: again and again, I encounter situations where Google helps me to find relevant articles in my own blog. In the latest article, I needed to use tables. The unfortunate thing is that the blog engine provides no hints when it comes to typing Markdown code, and so I had no idea how should I create tables. I remembered that I already used tables, but where? I tried to find myself, by walking through old articles, but unsuccessfully. Then I typed “table site:blog.pelicandd.com” in Google, and here it is, the article I was searching for. If this is not magic, neither is Santa Claus.
OK, I hear you, Jimmy from Example Corp. working on the new super-secret product™: making the internal documentation public?! What am I, out of my freaking mind?!
I already explained why most companies are really reluctant for opening their source code (and yes, I found the article by searching for “secrecy site:blog.pelicandd.com” on Google). When it comes to internal documentation, arguments against making it public seem even weaker. If you do a great job and have great documentation, publish it as an example, to inspire others and to show how great you are.
On the other hand, you have an extremely important benefit: your own billion-dollars search for free, with even less clicks (in Chrome, users can search for something by typing this thing in the address bar) for your team.