Writing documentation, is harder than writing code.
If you thought writing code is harder, my experience tells me that writing documentation even more so!
In the calculus of communication, writing coherent paragraphs that your fellow human beings can comprehend and understand is far more difficult than tapping out a few lines of software code that the interpreter or compiler won’t barf on. ~ Coding Horror
If its not documented, it doesn’t exist.
For open source projects, ‘getting started’ documentation is usually good these days. But once you run into some obscure issue or an edge case – you would have to resort to reading the code and documentation would mostly fail.
This is the time, when people are encouraged to document there finding and help out improving documentation. But as it would, code moves at a far more pace than documentation can.
Reading code might be an incidental task that you do while figuring out the issue with the code. But, it should actually be done as an activity of its own too. It’s widely agreed that reading great code definitely improves one’s own programming skill.
My experience while doing these ‘code reading’ exercises have been a revelation in terms of the knowledge that one can gather and the depth of the understanding.
I have realized that reading through the issues and comments listed on rails, has made me more knowledgeable with the code base than the documentation itself could ever do. Also, reading through such a huge code base like rails – is difficult to understand just by reading it. The issues and the comments / discussion on them is the best form of documentation. More like FAQs.
Smitten by this habit of reading through issues and the comments – I have decided to start *documenting* these understandings as blogpost series where I would take up the issue listed on rails/rails and then document my understanding of the behavior and summarize the comments.
Hopefully, that’s going to be helpful to all of us
– Code Reading Groups – Code is not Literature