Google Search is great, or why should your internal documentation be public

Arseni Mourzenko
Founder and lead developer
161
articles
February 6, 2018
Tags: featured 8 communication 25 productivity 33

Re­cent­ly, I an­swered a ques­tion on Pro­gram­mers.SE about doc­u­men­ta­tion tools such as Con­flu­ence for the in­ter­nal doc­u­men­ta­tion of the pro­ject. My an­swer was bad­ly writ­ten and I had no enough time or in­ter­est to rewrite it cor­rect­ly, so I re­moved it. There was, how­ev­er, one in­ter­est­ing point I want to rant about more in de­tail.

In my an­swer, I was telling that the per­son should chose a doc­u­men­ta­tion tool based on six cri­te­ria, in­clud­ing this one:

It should have a search fea­ture which works. Note that there are cur­rent­ly no tools which pass this cri­te­ria.

This is, it seems, a broad prob­lem which cov­ers near­ly all web­sites. I'll first ex­plain why search is im­por­tant, and then rant about the lack of prop­er search it­self.

Doc­u­men­ta­tion search fea­ture should work

The prob­lem with in­ter­nal doc­u­men­ta­tion is that of­ten, it's nev­er read. Why?

Ob­vi­ous­ly, be­cause in an open space (and who cares about pri­vate of­fices?), it's easy to shout your ques­tion and wait for an an­swer from your cowork­ers, rather than make an ef­fort open­ing the doc­u­men­ta­tion and even­tu­al­ly find­ing the rel­e­vant part of it and read it.

This means that what­ev­er can sim­pli­fy the work­flow (open the doc­u­men­ta­tion, find the rel­e­vant part, read it) should be done. Un­for­tu­nate­ly, I've seen many teams do­ing what­ev­er they can to make the work­flow rather un­bear­able.

  1. Open the doc­u­men­ta­tion.

    What about hav­ing to go to an in­tranet site with a very ex­plic­it URI such as http://192.168.1.94/sphynx/abby/default, then be­ing re­quest­ed to en­ter your user name and your pass­word, giv­en that nei­ther of two cor­re­spond to your LDAP ac­count (“Why are you, damn fools, cre­at­ing an in­tranet site, since you are not even us­ing the only ben­e­fit of an in­tranet vs. in­ter­net app?!”) and should be found on one of your post-its, and when you've fi­nal­ly found it, it ap­pears that it's no longer valid, be­cause of 30-days pass­word ex­piry pol­i­cy (“Why are you, damn fools, mak­ing your com­pa­ny less safe while an­noy­ing every­one?!”) which re­quires you to call a sys­tem ad­min­is­tra­tor to get a new pass­word?

  2. Find the rel­e­vant part.

    Quick UX ex­er­cise. Should you use a tree or tags to or­ga­nize doc­u­men­ta­tion ar­ti­cles? Beep. Those who an­swered “a tree” are wrong. A tree im­plies ex­clu­siv­i­ty: an ar­ti­cle can be found in one and one only lo­ca­tion. The right an­swer is “tags”, be­cause it makes it pos­si­ble to lo­cate the same ar­ti­cle fol­low­ing dif­fer­ent trains of thought. At a very ba­sic lev­el, imag­ine a per­son search­ing for a way to re­move a prod­uct. Un­for­tu­nate­ly, there is noth­ing re­lat­ed to “Prod­uct re­moval”, be­cause the au­thor of the ar­ti­cle put it in Deletion\Products. In prac­tice, tree ex­clu­siv­i­ty be­comes par­tic­u­lar­ly harm­ful in more com­plex sit­u­a­tions than that.

    Un­for­tu­nate­ly, most doc­u­men­ta­tion tools I've seen are en­cour­ag­ing a tree as a pri­ma­ry or­ga­ni­za­tion­al tool, which im­pacts very neg­a­tive­ly the search ex­pe­ri­ence (and can lead to con­tent du­pli­ca­tion, con­tent ob­so­les­cence and oth­er ugly things).

  3. Read it.

    Imag­ine that the in­ter­nal doc­u­men­ta­tion ac­tu­al­ly an­swers your ques­tion, but is writ­ten by a per­son who should nev­er list writ­ing skills in his CV. I've seen code bases where every com­ment (99% of com­ments be­ing use­less, by the way) con­tained er­rors, mis­spellings and a mix of French and Eng­lish (in code bases writ­ten by French coders). Are those peo­ple able to write an ar­ti­cle? If they write one, would it be of any help?

    Most con­tent writ­ten by IT per­son­nel (in­clud­ing man­agers) in France is not only com­plete­ly use­less, but also com­plete­ly un­read­able. I don't know why those peo­ple are even writ­ing any­thing, be­cause they are clear­ly un­able to ex­press even el­e­men­tary ideas.

Ef­forts can be made to make the doc­u­men­ta­tion a pri­ma­ry can­di­date for team mem­bers look­ing for help. If we fo­cus specif­i­cal­ly on the sec­ond step of the work­flow, a search fea­ture can make all the dif­fer­ence. Spend­ing ten min­utes ex­plor­ing the tree or brows­ing through a list of tags is not a fun thing when you have to meet the dead­line which, by the way, is in three days. Typ­ing what's on your mind in a text box and run through the first five re­sults looks much more promis­ing.

Ide­al­ly, a mem­ber of a team should be able to open a web page (which has an ex­plic­it, easy to re­mem­ber URI, such as http://docs.example.com/), ex­press his mind in a text box, and be amazed by a set of par­tic­u­lar­ly rel­e­vant re­sults.

But I'm still wait­ing for a prod­uct with a search fea­ture that works

So the search should work.

Ex­cept that it doesn't on most web­sites. Many web­sites are just com­plete­ly brain dam­aged, and should plain­ly re­move their search fea­ture. Some are not brain dam­aged, but don't work well ei­ther. A few have a search fea­ture which works, like Stack Ex­change, giv­en that Google still ob­tains a slight­ly bet­ter rel­e­vance when do­ing a search with­in a giv­en Stack Ex­change site.

I un­der­stand why is this like that. Google spent a huge amount of mon­ey on their search en­gine, and it be­came an ex­cel­lent prod­uct. Oth­er com­pa­nies can't spend that much mon­ey on a search fea­ture with­in a doc­u­men­ta­tion tool, which means that their search will prob­a­bly be in­fe­ri­or.

What I don't un­der­stand is that there is an ob­vi­ous so­lu­tion:

Open your doc­u­men­ta­tion to the pub­lic.

And by pub­lic, I mean Google. And by Google, I mean your own team.

Two hours ago, I was writ­ing an­oth­er ar­ti­cle. In this ar­ti­cle, I want­ed to put a link to a re­cent ar­ti­cle talk­ing about roadmaps. And some­thing else. I don't re­mem­ber what ex­act­ly, but I re­mem­ber that roadmaps were men­tioned.

From there, I had a choice. I could:

When writ­ing this ar­ti­cle, I was again faced with a prob­lem. I re­mem­ber writ­ing about trees and tags, but where? Again, “tree site:blog.pel­i­can­dd.com” got the first search re­sult right, giv­en that the word “tree” wasn't even men­tioned in the ti­tle, and wasn't the pri­ma­ry key­word I was think­ing about when I was writ­ing the cor­re­spond­ing ar­ti­cle (which also means that I would get the tags wrong, miss­ing the tree tag if my ar­ti­cles were tagged for search pur­pos­es).

Edit: I'm still amazed by the con­ve­nience of Google search. When writ­ing an an­swer on Pro­gram­mers.SE, I want­ed to put a link to a blog ar­ti­cle where I dis­cussed the prob­lem of in­tro­duc­ing qual­i­ty stan­dards in the mid­dle of the pro­ject. Since I wasn't re­mem­ber­ing the ti­tle, I glanced for a few min­utes on the list of ar­ti­cles, and then typed in Google “style­cop bet­ter site:blog.pel­i­can­dd.com”. Mag­i­cal­ly, it showed the ar­ti­cle, ex­act­ly the one I was look­ing for.

Edit: again and again, I en­counter sit­u­a­tions where Google helps me to find rel­e­vant ar­ti­cles in my own blog. In the lat­est ar­ti­cle, I need­ed to use ta­bles. The un­for­tu­nate thing is that the blog en­gine pro­vides no hints when it comes to typ­ing Mark­down code, and so I had no idea how should I cre­ate ta­bles. I re­mem­bered that I al­ready used ta­bles, but where? I tried to find my­self, by walk­ing through old ar­ti­cles, but un­suc­cess­ful­ly. Then I typed “table site:blog.pel­i­can­dd.com” in Google, and here it is, the ar­ti­cle I was search­ing for. If this is not mag­ic, nei­ther is San­ta Claus.

OK, I hear you, Jim­my from Ex­am­ple Corp. work­ing on the new su­per-se­cret pro­duc­t™: mak­ing the in­ter­nal doc­u­men­ta­tion pub­lic?! What am I, out of my freak­ing mind?!

I al­ready ex­plained why most com­pa­nies are re­al­ly re­luc­tant for open­ing their source code (and yes, I found the ar­ti­cle by search­ing for “se­cre­cy site:blog.pel­i­can­dd.com” on Google). When it comes to in­ter­nal doc­u­men­ta­tion, ar­gu­ments against mak­ing it pub­lic seem even weak­er. If you do a great job and have great doc­u­men­ta­tion, pub­lish it as an ex­am­ple, to in­spire oth­ers and to show how great you are.

On the oth­er hand, you have an ex­treme­ly im­por­tant ben­e­fit: your own bil­lion-dol­lars search for free, with even less clicks (in Chrome, users can search for some­thing by typ­ing this thing in the ad­dress bar) for your team.