[emorse]

As far as this discussion goes, I think that code is documentation. If you need to figure out how something works, going directly to the automation code will give you the right answer. If the code is difficult to understand, that's more of a quality issue, and the same problem happens with word documents.

[chimeracoder]

> As far as this discussion goes, I think that code is documentation.

"Code as documentation" can be an okay answer if the question is "what is the behavior of this system"? But it's a bad answer for the question "what is the intended behavior of this system, and what assumptions does it run under?"

Looking back at a piece of code months (or years) later and not knowing if a particular edge case that you're running into was actually the intended function or not is not particularly fun.

The power of writing documentation is not just in the end product; it's that it serves as a forcing function for the developers to confront their own thought processes and make them explicit. It's possible to write code that makes all of its assumptions explicit and clearly states its contracts up-front, but in practice, it almost never happens without significant external documentation (whether that comes in the form of explicit code docs, whitepapers, or ad-hoc email threads and Slack conversations that need to be pieced together after-the-fact).

[rhizome]

One of Fred Brooks's principles is that the manual is the spec, that there should not be any behavior in the software that is not in the documentation, and the documentation comes first.[1] A kind of old-school TDD.

1. https://en.wikipedia.org/wiki/The_Mythical_Man-Month#The_man...

[robomc]

Code as documentation only works if all your infrastructure is managed programatically, there are good tests, the code is good, and overall complexity is low.

I mean, if your downstream partner calls up to say that the custom analytics feed from your xyz service is returning null data, but not erroring, and the guy that implemented that feed (with rolled eyes, thinking it was an inelegant hacky concession to a noisy customer) left in 2015, where do you even start? How much code from how many codebases and configuration management repos are you going to have to read through just to work out what kind of problem you've got?

Some type of high level documentation - what services / products exist, what infrastructure does each use, how is each one managed and tested, what is worrisome about it or what has tended to go wrong in the past - is going to help a lot.