Lack of good documentation in the Android community

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.

I found this to be extremely common in the Android community and as someone who’s coming primarily from a Ruby background where documentation for many popular gems is excellent, I find Android development extremely frustrating. Android development on a technical level is not that difficult. It’s just Java at the end of the day and frankly it feels eerily similar to writing front end web applications using JavaScript frameworks like AngularJS and EmberJS with the only major difference being Java (Android) vs JavaScript (web). But the lack of documentation makes it unnecessarily difficult and raises the bar for new developers wanting to learn Android. It’s almost as if seasoned Android developers are doing this on purpose to protect their jobs or something.

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.

About the Author Chris Jeon

Software developer currently focusing on Android development.