Using README Files for System Documentation

I’ve become a huge fan of README text files scattered throughout the filesystem of any managed systems. When creating directories for various purposes, such as SFTP-only users, home directories for non-person users, data directories, etc – the README will serve well to document the files and the directory in general.

There are many places you can use a README file for better clarity. Consider some of these locations:

  • NFS mount: where is the directory actually located?
  • Mountpoint root: what directory is this supposed to be normally?
  • Network shares: like NFS, describe where the directory is actually located – and why it is shared.

Lots of things can be described in a README file.

What are these files? This is the most obvious question to answer. Are they backup files? Are they one-time backup files? Are these files part of a project?

How long is the directory or files needed? Can the directory be eliminated at another time?

Where is the directory located? For network shares – and for disk mounts – labelling the directory in the README can help. This way, when the disk is mounted elsewhere (for recovery for instance) its actual mount point will be recorded. In the case of a network share, it helps to identify where the share is coming from without having to resort to other tools.

What should be done in the future? Putting a modest amount of future plans in the file helps to show future admins what was going on at the time the file was written.

When was the file written? The file itself should contain the date; otherwise, no one will know when the file was written. The filesystem metadata (file time) cannot be relied on as it can change for various reasons.

How does this configuration or set of files deviate from the norm? If you have a different set up, then a description of the configuration is in order. Otherwise, a future admin – or yourself – will not realize that things are different and may spend time figuring that out when they don’t have to.

Give an overview. Many directories will be comparable to large “containers” (like /data); describe what each of the directories are used for in a short paragraph or two.

When you go about creating a text file like this, remember several things:

  • Use text-only with no formatting. Don’t make it a WordPad document, nor an OpenOffice document. The document should be readable by a minimal environment.
  • Check clarity. It won’t do to go to this trouble and then find later that the writing is incomprehensible.
  • Use proper spelling, grammar, and punctuation. Reading something that requires basic fixes in grammar and spelling can be grating and is not good for your professional image.
  • Revisit the README file once in a while. Updating the file with new information will prevent mistakes and errors from creeping into the document, and will prevent future admins from relying on out-of-date information.
  • Make more than one if necessary. This is almost never necessary – but when it is, don’t be afraid to do so. Name the file README.something to help future readers.
  • Do your research. If you have questions about what a directory is for, what the files are for, or why things are the way they are, ask. Someone will have to do this one day anyway – so do it now and document it.

If you make a regular habit of sprinkling a little documentation like snow, you won’t regret it.

    Leave a Reply

    Fill in your details below or click an icon to log in: Logo

    You are commenting using your account. Log Out /  Change )

    Twitter picture

    You are commenting using your Twitter account. Log Out /  Change )

    Facebook photo

    You are commenting using your Facebook account. Log Out /  Change )

    Connecting to %s

    %d bloggers like this: