Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Right, and we do do that for decisions that affect more than the people involved in the debate. However, we also have a wiki, and so anyone can look at it and see how a habit of writing things down decays - because people may write it, and read it, but nobody maintains it or cleans it up.

The only worthwhile document is a document with a clear owner that is routinely updated. This does not scale beyond a few pages per user.

When you talk to someone, you get their view at this point in time. You don't accidentally get their view five years ago which they've since revised; you are guaranteed to get, if not the accurate version, then at least the current one. When you talk to multiple people, you even have a chance to get the correct one. Notes cannot defend their argument and so must be taken on faith - or else to confirm your understanding, you end up talking to someone anyways!

In code, the best documentation is the test, because it must be correct. The second best documentation is a comment, because it's right there and hence hard to miss. Third is an external specification referenced in the README, because they generally change much more slowly than the code. Distant fourth is a self-written document in the same repository, because after all, how do you notice that something didn't change during review?



Ah but you see, in coding, before you write the test, you need a software developer and/or a team lead who gives a shit about writing tests.

So it all comes back to the good ole "give a shit" factor.


And I think this is somewhat the original talk's point: if the superiority of a given method is predicated on things happening (which rarely do) or things not happening (which often do), then it might not be superior.

If TDD is superior if leads write tests, but leads rarely write tests, then is it superior?

If meetings are superior if everyone shows up on time, prepared and generates documentation of the meeting, but nobody ever does those things, then are meetings superior?

Tl;dr - Be honest about your team's reality, and choose the optimal option for that reality.




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

Search: