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.


Comments on this page:

By Ewen McNeill at 2014-06-18 06:50:18:

I'll offer a counter point to your second broad problem: long, long, ago I started writing "Written by Ewen McNeill...., DATE" at the top of basically every script (and other piece of source) that I wrote -- certainly everything more than "one command line" long. Before I write anything else. When I'm putting those things onto a shared system, it's an implicit reminder "would you want to put your name on this" -- and that tends to lead to some of the rough edges being rounded off or the script/program being made more robust (or at least the assumptions about context being documented).

The same has been said about writing documentation: if it's unnecessarily complicated to explain, or you're feeling "I don't really want to explain this in public", then maybe that's a sign that the thing being documented needs more attention before it's ready to be called finished.

I do agree that there needs to be "documentation for the stakeholders" and "documentation for internal consumption" anywhere that there isn't a huge amount of backing for complete openness (and passwords should be in a separate password store). But it might be worth considering having the documentation in two levels of visibility ("our department IP range", "user ID in sysadmin team", perhaps) -- and a convention that anything that is "user ID in sysadmin team" needs a note in it explaining why it's been classified that way. (And some topics might benefit from being split into "public view", "internal implementation notes".)

Ewen

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, View Normal, Add Comment.
Search:
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.