The Write The Docs conference is running right now, and a session just got done about search-oriented documentation (the slide-deck) and it hit all kinds of bells for me. I'm a technical user of a very wide variety of documentation, and I work in an industry that coined the term RTFM. We are consumers of documentation in all of its various forms:
- Straight up manuals on paper, sitting on a shelf, that arrived with the product (back when manuals still shipped with product)
- Offline manuals in CD-ROM form (in that time between when physical manuals stopped shipping and everyone had an Internet connection).
- Online manuals in HTML form.
- Support databases listing targeted resolutions of problems and technical notes hilighting obscure bits of config-trivia.
- Random Internet forums with posts from fellow lost people having the same problem.
- Random wikis.
- Vendor-specific product forums attempting to provide a 'Community' experience to support (and take some load off of their support people).
- Internal ticketing databases.
- Internal and external bugtrackers.
How do we find all that crap?
Google.
This is why none of us have cracked open an offline manual (or put in a CD-ROM) in years. Our portal into documentation is the search-engine, either the majors or the one built into our internal tools (where the majors can't find it). But search is our index.
For those of us who write end-user visible documentation, keeping this in mind is paramount. Enhancing searchability means enhancing metadata like tags, so tag your doc with the words users actually search for not their actual names. As a consumer of documentation I can only cheer this kind of effort to improve discoverability.
Okay, obviously it's been a long time since I commented on your blog, because the sign-in process was kind of onerous for me. Neither OpenID or Wordpress.com options worked for me to sign-in so I could comment.
Documentation is, at best, way, way down the list of things sysadmins want to bother with, even though it's incredibly useful. And, I mean, *internally* useful to fellow sysadmins, not necessarily even to end-users, but we still have a hard time actually making ourselves write it. Much less writing something that is easily comprehensible and useful. It seems like every time I take over a new network, which I've done at least a half-dozen times, I have to spend a month or two just figuring out where everything is on the network and why it was configured any particular way.
At my current job, I've decided to break that cycle and start documenting what I do on a day-to-day basis. For a change, I don't want the next guy to come in behind me and wonder about a password or a support vendor phone number.
So, I started a teeny, tiny "personal" wiki.
I posted about it at my new blog, http://www.jkhoffman.com/2011/11/a-personal-wiki/, even though you may remember me as the writer from Diary of a Network Geek.
And, if you want to put that on an intranet, or even use it as a webpage, that can be done, too. All on one page and seachable, internally as well as "Google friendly".
Speak for yourself :)
This is not a "sysadmins" issue. I'm not you. I enjoy documenting things very much and have for 19 years now. There are many like me.
It's an issue of professionalism, regardless of IT career choice.
Yep, something is broke in commenting other than google. Will have to poke at that.
I'm just happy that the tech-writers out there are getting this message! I'm a consumer of their stuff so that's better for me. And as I have to produce operational doc for my own pack of devs, it's a good idea for me too.
Haha! Well, you're the first one I've run into in over 20 years worth of doing sysadmin work!
But, you're right. It IS an issue of professionalism and it's a shame that more system administrators don't think so. It would have made my job so, so much more easier over the years if they had!