Would I be comfortable documenting our systems in some sort of public?

June 18, 2014

One of the questions that I wind up asking myself any time I think about using wikis for sysadmin purposes is how comfortable I am having our system documentation sitting out in some sort of public view. Around here there are effectively two or three levels of public view we could have; it's easy enough to make it so that our documentation could be visible to the world, to anyone at the university, or only to people inside the department.

There are two broad problems that I see with any degree of exposure for system documentation. The first broad problem is what to do about sensitive information, ranging from stuff that would be useful for attackers through stuff like license keys and vendor support site passwords all the way to potentially personally sensitive information about particular people (which comes in many forms).

In a way the second broad problem is worse: it is the potential effects of writing with outsiders looking over your shoulder. Not everything we do as sysadmins is beautiful and elegant, to say the least. To document things in public is to open all of the things you are not as proud of to public scrutiny. I think you're inevitably going to write with this on your mind, with at least some degree of urge to self-censor, to maybe not write down some things in the open or to bend your phrasing to take the rough edges off and put a good gloss on things. I rather suspect that this is going to do undesirable things to your documentation in the long run.

(Some of these issues probably don't apply as much in a company as they do in a large university (even inside a large department). To put it one way, even a department is a pretty public place, especially once you start thinking about graduate students, postdocs, visitors, and so on.)

The upshot is that while part of me would like to open up our documentation to at least everyone in the department, the larger part of me has wound up feeling that sysadmin documentation needs to happen in private (at least around here). Writeups for public consumption are best done completely separately.

So the answer to the title of this entry is 'no, not at all'. Even if we could reliably segregate all of the sensitive information away from the public portion of the documentation, I would prefer not to have the issues that come from writing internal documentation while knowing that some degree of 'the public' may be reading over my shoulder.

Written on 18 June 2014.
« My view: a wiki by itself will not solve your problems
Some notes on Go's godoc and what it formats how »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Wed Jun 18 01:26:58 2014
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.