Programmers are famous for not doing a great job of documenting theinterfaces of their projects (whether these are libraries with APIs,protocols, programming languages, or whatever). The problems that thiscauses for people who are trying to use your work are well known, butit's recently struck me that open source projects in particular havean additional issue.

In the absence of documentation, people working with open sourceprojects can always read the source to find out how to do something, todiscover the interface that the

I've written before about sysadmin style use of version control , where we typically use a VCS for documenting the livetree instead of developing something. Recently I ran into a mistake that modern VCSes and this style of working combinetogether to enable: deleting a file from the live directory tree butforgetting to delete it from the VCS.

Since the live tree is, well, live, deleting the file actually takeseffect and so you don't notice anything wrong. In fact, in a sensenothing is wrong