5 ms·

> The special master at times seemed in disbelief, as when he questioned the engineers over whether any documentation existed for a particular Facebook subsyste

> The special master at times seemed in disbelief, as when he questioned the engineers over whether any documentation existed for a particular Facebook subsystem. “Someone must have a diagram that says this is where this data is stored,” he said, according to the transcript. Zarashaw responded: “We have a somewhat strange engineering culture compared to most where we don’t generate a lot of artifacts during the engineering process. Effectively the code is its own design document often.” He quickly added, “For what it’s worth, this is terrifying to me when I first joined as well.” The cynic in me wants to say that not documenting certain decisions is a common method of hiding immoral decisions.

namelessoracle 4y ago
The cynic in me says it's building your own job security. Documentation only really gets created if leadership forces the issue in my experience. You also get to sell the refactor/rewrite because "nobody understand the existing code".
- 988747 4y ago
  I've been a programmer for 15 years and I've never seen it done for "job security". I think this is mostly about low tolerance for boredom of most programmers: writing code is exciting, documenting it is boring, so you do not do it unless forced to.
  - namelessoracle 4y ago
    Ive seen people "neglect" to offer training peers or document things before to protect their own position. Anecdotes and all that. I mean people "usually" wont say that out loud of course.
roland35 4y ago
Trust me, at (most) big tech companies there isn't anything that nefarious going on at the engineer level. In fact everyone basically agrees that improving documentation is important, but it constantly gets swept aside in the constant churn of new features, fires to put out, and frequent meetings. Information gets spread out across various docs, wikis, readmes, etc. What ends up happening is each part of the system has a "point of contact" who is the go to for that piece. Lots of decision history is in the heads of team elders. Hopefully they are still around!
adamsmith143 4y ago
So FAANG is held as the gold standard in the industry and this is their best practice? >We have a somewhat strange engineering culture compared to most where we don’t generate a lot of artifacts during the engineering process. Effectively the code is its own design document often.”
laweijfmvo 4y ago
Imagine that someone asks you to modify a service; so you study the code, make the change, test it, and push it. Now imagine they ask you to update all the docs/wikis to reflect the recent changes, or more realistically you just create another one and store it wherever you feel is appropriate. In my experience there’s a ~10% chance an up to date piece of easily discoverable documentation exists for any service or component, and there’s a ~90% chance at least one out of date document exists. The later seems much more harmful, like when you realize some PM has been referencing an out of date doc for the last 9 months.

namelessoracle 4y ago

The cynic in me says it's building your own job security. Documentation only really gets created if leadership forces the issue in my experience. You also get to sell the refactor/rewrite because "nobody understand the existing code".

988747 4y ago
I've been a programmer for 15 years and I've never seen it done for "job security". I think this is mostly about low tolerance for boredom of most programmers: writing code is exciting, documenting it is boring, so you do not do it unless forced to.
- namelessoracle 4y ago
  Ive seen people "neglect" to offer training peers or document things before to protect their own position. Anecdotes and all that. I mean people "usually" wont say that out loud of course.

roland35 4y ago

Trust me, at (most) big tech companies there isn't anything that nefarious going on at the engineer level. In fact everyone basically agrees that improving documentation is important, but it constantly gets swept aside in the constant churn of new features, fires to put out, and frequent meetings. Information gets spread out across various docs, wikis, readmes, etc. What ends up happening is each part of the system has a "point of contact" who is the go to for that piece. Lots of decision history is in the heads of team elders. Hopefully they are still around!

adamsmith143 4y ago

So FAANG is held as the gold standard in the industry and this is their best practice? >We have a somewhat strange engineering culture compared to most where we don’t generate a lot of artifacts during the engineering process. Effectively the code is its own design document often.”

laweijfmvo 4y ago

Imagine that someone asks you to modify a service; so you study the code, make the change, test it, and push it. Now imagine they ask you to update all the docs/wikis to reflect the recent changes, or more realistically you just create another one and store it wherever you feel is appropriate. In my experience there’s a ~10% chance an up to date piece of easily discoverable documentation exists for any service or component, and there’s a ~90% chance at least one out of date document exists. The later seems much more harmful, like when you realize some PM has been referencing an out of date doc for the last 9 months.