If you have ever written a driver or picked up someone elses code you will recognize the need for documentation and examples on how to use it. I am writing loads of drivers these days and stugle with Vendor datasheets as well as HAL’s – usually I end up hacking and trying to understanding how it works and finally implement my own driver in a C++ class. If I left it there it would only be yet another layer to understand – for code to be really reusable you need documentation and examples.
Reading datasheets should normally solve the need for doc, but I often find that information is left out or that it actually work differently than expected – these details are crucial to get down in code and doc. Maybe it’s me who have misunderstood something, but if I don’t write that down you will struggle to correct my mistakes or improve my code. I am no different than other developers – I like to do my own things – things that are productive for me. I have mates that do the same, but their things are seldom productive for me unless they bother to complete and document their work.
One of the worst tasks you take on as a developer is to try to fix someone elses work that is half-done, not tested and with no doc. That is what I am doing at moment – it’s no fun 🙁