This is a off-topic post that came out of the SearchView implementation post I wrote here.
This is something I’ve noticed consistently while working on Android apps. The Android community seems to not put too much importance on documentation. When you look through popular Android libraries like DBFlow (a popular ORM for Android), and look at the README or the Wiki, there’s literally zero information on how to use the library. The most I’ve seen most open source projects do is provide a sample app that displays how the library can be used. While this is definitely helpful, it’s not the same as looking through the documentation to quickly get a sense of how the library can be used and integrated into your app.
When I was working on implementing the custom SearchView, I even remember coming across an answer that went something like, “I had this problem, but I figured it out by looking through the Android source code”. Dot dot dot… I mean… sure, I guess the source code being open for inspection is one of the benefits of open source, but c’mon who has the time to look through the Android source code??? It’s one thing if the problem is obscure enough that it warrants looking through the Android source code, but if it’s caused by due to lackluster documentation, then it’s a problem that can be more easily solved by us developers being more disciplined about documenting the software we produce. I once had to look through the Ruby on Rails source code to debug something, so I’m not saying looking through the source code of a framework to debug something is not totally unreasonable.
We as a community need to do a better job of documenting our software, myself included. I’m certainly not perfect, and I’ve been lazy before when writing those README.md files on the freelance projects I work on, but being more disciplined as a group will easily save hundreds if not thousands of our precious time for our fellow developers.