Blog posts like this are always optimistic and celebratory. Sometimes it's warranted, sometimes it isn't. I'd love to hear how people on the ground at Etsy actually feel about it.
We got runbooks/ - these are hard about how. And they are prone to some degree of decay, I won't lie about that. Thus, runbooks/ is encouraged to be changed, extended, modified, clarified. runbooks/ isn't anything pretty, runbooks/ is the oil- and coffee stained notebook with more loose paper than bound paper somewhere on top of a machine and we're all going to die if you lose runbooks/.
And on the other hand, we have doc/. doc/ doesn't change without a lot of discussion, and doc/ defines hard standards. doc/ won't generally help you with an immediate problem. doc/ explains why things are defined the way they are - or if this is just an arbitrary naming convention.
The thing I suggest here is that if you are going to document the function, it should only be the WHY. The how can change and the documentation doesn't really decay. If you are making a new function you have to start with the why and if you can't then you shouldn't be adding a new interface. This also helps build a better picture of how the pieces interface together.
The other is when someone write “if you need to do X” with no information about how you’d know if you need to do X
While I agree with you, the latter problem is particularly frustrating to encounter.
Solving the conceptual problems feel more like an exploration or a learning experience, and I rarely feel like time spent solving those problems is wasted even if it's very meandering.
Solving the "how do I do this?" problem rarely feels like more than a very isolated learning experience, and more often it feels like banging your head against a wall. Doubly-so when the documentation is obsolete and leads you in the wrong direction.
Learning the basics of media compression is interesting and worth spending time on. But I'm going to hate myself if I have to spend 6 hours figuring out how to convert a file using ffmpeg.
Here's an example: I need to generate a report where I need to cross-reference data from A and B. I need to know where A is going, where B is going, how to modify the schema of the events going into B to add a specific piece of data, where we can process inputs from A, how to do the join, and how to add the report into the dashboard.
On the one hand, I could ask the surface level question "how do I generate the report for ____?" but really there's a whole lot to unwrap, and what I need is the information to do the unwrapping. I don't need a course on statistics, I just need to understand our specific architecture.
The answer (from my experience at Etsy, anyway) to questions like:
> how to modify the schema of the events going into B to add a specific piece of data,
was "Run schema_modifier", the docs for which were frequently obsolete. Figuring out how to "run schema_modifier" was usually a very frustrating experience in that particular instance, whereas unwrapping the actual problem was usually less frustrating.