Item — HN Reader

I see this pattern at every company I work at:

You're the new guy. You look for documentation, you find something outdated, untouched for 6 years with a note that the page was migrated from some other system and is "work in progress".

If that thing was untouched for 6 years, it is logical to conclude that it no longer contains correct information. You read a few lines, see dead links and wrong information, you conclude that it is no longer useful.

The person that wrote the original wiki, still works at the company, but they now work on a different system and have no responsibility for that legacy system.

See, the issue is always the same: transfer of knowledge deteriorates with every person that quits or gets promoted. The system is now maintained by someone else, who has their own "wiki" on their own machine. The original, now useless wiki, should have either been deleted or updated. This doesn't happen.

This creates such waste on a global scale, that it is beyond comprehension. Whoever solves this issue, will surely help the human kind.

In summary, when a transfer of ownership for a wiki occurs, there should be a mechanism to make sure that it gets either deleted or maintained. Having new hires hunt for information, benefits no one, especially not the organization. Get your documentation in order, and you will save a ton of hours and improve productivity!

1 comments

A place i worked had a wiki, and i diligently updated the wiki with everything that i was doing, including screenshots and links to where i came about the correct solution to problems if necessary. Having to host a meeting every two weeks to basically put the wiki up on a projector and read from it, taught me within the first quarter to not bother with the wiki editing at all.

I had my own set of servers in a rack, and i synced home directories between my laptop, desktop, and the servers. When i left, one of my managers pulled up all edits from the wiki that i made (18 months prior!), and said "i thought you said you were good at documentation...?" I emailed him the tarball of my home directory. They obviously weren't paying me to write documentation.

There was also three ticketing systems, depending on what group whoever submitted a ticket either knew about or thought could handle it. There was a ton of notes in the ticketing system. I wasn't involved in stuff that people could complain about, so i only used the ticketing system when i would volunteer to help do NOC/sysadmin duties. There was no mindshare between the wiki and the ticketing systems.

There was also email. There was also several IRC channels, internally - each group would have a room for the devs and manager(s) for that group, and the managers and some devs were in the IT channels or the backoffice channels, it was a mess. I like IRC for emergencies and for basic communication, but stuff that isn't transitory or ephemeral ought be put in the wiki, not left to someone to figure out how to parse irc logs at some point in the future.

I still occasionally write detailed "how-to" guides, put up here and there on the internet - but i've still never found a decent software stack to self-host some sort of documentation repository, and oh how i've tried so many softwares...

This is a management failure. If you let hundreds of people run amok you're going to have nonsense documentation strategies. First: you can't have a group of people dedicated to putting out fires who also do other things. Don't have NOC do database backups, for instance. NOC should NOC, and their "guidebook" should be in the same place as everyone else's. As soon as you relieve the pressure on different sub-organizations or teams or groups, you can probably successfully mandate that X hours per week of the team's budget should go to pruning, editing, correcting, and adding to the documentation. Secondly, the manager or at least the senior team member should get an easily digestible digest of all edits/new entries posted to the documentation system, ideally daily. If the documentation starts to drop off or becomes lower quality, that should be addressed quickly. Third, a universal glossary would be excellent.

i wrote too much to agree with your premise, but other than the last paragraph being a non-solution, i didn't really add anything. Oh well.

I similarly do a lot of documentation, mainly because it helps me to understand the scenarios and contexts, but also because I'm aware that it can short-cut the (expensive) learning curve for new hires.

But it's pretty universally un(der)-appreciated because there's no direct line from good documentation to "improved bottom line". I've not come across documentation-related KPIs, especially now that Agile gets misinterpreted as "no documentation" - sure, the code can change regularly, but the fundamental concepts barely change and should have a couple of levels of documentation (detail and overview) as they're fundamental to the business itself, and user processes change slowly enough that updating existing diagrams is a progressive, not wholesale change.