4 ms·

how to make sure code and doc are in sync? who reviews doc changes?

• gtirloni 7y ago
  I often get these questions from agile people (not saying you're or aren't) and my answer is always: the same code reviews that ensure there aren't code smells. Lack of documentation is a code smell to me. To be clear, if docs are just translating to English what the code is already expressing then they are bad. They should be high level, explaining odd cases, etc. If they go out of sync, you fix them because your future ability to understand the code depends on it. I've had PR's rejected because they only added comments saying that "they will get out of sync". I've had documentation projects canceled because "they will get out of sync". It makes me really sad when a new hire struggles to understand basic things in our code base. </rant>
• byoung2 7y ago
  There are a few reminders in the PR template in github. You have to check boxes for tests added, documentation added, A/B test team notified, etc if you are adding new functionality. The code review process keeps you honest, and CI will reject the PR if something is missing.