this is an excellent post and quite relevant. i have found this kind of epiphany as well while writing a python based framework at my company. i would extend the README driven approach to even suggest a developer blog driven design methodology, since it allows for a more dynamic way to clarify points and also add diary entries for 'thinking aloud' while you are building complicated libraries.
- they don't get updated
- they don't get patched
- they don't ship with the software
- they break when the user dies / moves / leaves / changes software
- they have a lower signal to noise ratio
You are correct. So I suppose I should alter my previous post by saying that it is a good way to go iff you are also willing to be diligent in your updates to keep the documentation as current as possible.
