Hacker News new | comments | show | ask | jobs | submit login

I'm going to mostly disagree with everyone here, much to my karma's detriment ;P

I agree the end-goal should be infrastructure as code, and everyone here has covered those tools well. You also want monitoring across your infrastructure. Prometheus is the new poster-boy here, but the Nagios family, and many other decent OSS solutions exist as well.

But you still need documentation. Your documentation should exist wherever you spend most of your time. Some examples:

* If you spend most of your time on a Windows Desktop, doing windows admin type things, then OneNote or some other GUI note-taking/document program makes sense.

* If you spend most of your time in Unix land(linux, BSD, etc) then plain text files on some shared disk somewhere for everyone to get to, makes WAY more sense. Bonus if you put these files in a VCS, and treat it like code, and super bonus if your documentation is just a part of your Infra as code repositories.

* If you spend your time in a web browser, then use a Wiki, like MediaWiki, wikiwiki, etc.

In other words, put your documentation tools right alongside your normal workflow, so you have a decent chance of actually using it, keeping it up to date, and having others on your team(s) also use it.

We put our docs in the repo's right alongside the code that manages the infrastructure.. in plain text. It's versioned. We don't publish it anywhere, it's just in the repo, but then we spend most of our time in editors messing in that repo.




I totally agree, but having "infrastructure as code" means less documentation.

Instead of documenting all the commands involved in configuring a machine as service X (ssh, run apt-get, paste this, etc.), I have documentation on how work with the configuration management system (roles in the roles/ directory, each node gets one role, commit to git, open PR, etc.). That documentation is in .md files in the config management source repo.

Instead of documenting how to rack a server (print and attach label to front and back, plug power into separate PDUs, enter PDU ports into management database, etc.), I document Terraform conventions (use module foo, name it xxx-yyy, tag with zzz, etc.).

It ends up being less documentation, as the "code" serves to document the steps taken, so the documentation can be higher level. Or if it isn't less documentation, it is documentation that needs to be updated less often, so hopefully there will be less drift between docs and what actually exists.


Yes, I didn't cover what goes into the documentation, as that is mostly site-specific, but I mostly agree with you... mostly. Instead of documenting run apt-get, ssh, etc to start up service X, now you have to document how your tools are setup, Ansible, Terraform, etc. Plus your code needs documentation about why it's setup the way it is.

You still need high-level stuff, policies, etc. Security guides, none of this has changed.

You also have to document your snowflakes, how you handle the wacky snowflakes, why they exist, etc.

Ideally your documentation should be such that it would pass the hit-by-a-bus test. I.e. if you or your entire team got hit by a bus, someone with a clue could come in, read your documentation and continue.

My docs are not at that stage, but every time I mess about with something I try to read through the docs attached, and verify and add to them, so that hopefully someday we will get there.


Sit down with another sysadmin and have them go through your Terraform repo; if they have to ask more than 3 times why something is done a certain way, your "infrastructure as code" as documentation is insufficient.

Source: 16 years in various ops roles


Ah the good old "self-explanatory code that needs no documentation".


More like code usually required extra documentation explaining it in a higher level language, but nowadays we just write the program on that higher level language so this extra documentation has gone away.


Windows sys admin here. OneNote is fantastic for IT documentation. I like that you can drag and drop a screenshot (no uploading to a wiki), store spreadsheets, word docs, PDFs, etc. and easily search for information via the built-in functionality.

We have used it for years and it has worked great for us.




Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact

Search: