Documentation: it’s really important
I’m going to take this lesson to talk about the elephant in the room when it comes to programming: documentation.
I’ve said it before, and I’ll say it again: documentation is really important. Whenever we write code we should always think of a way to document it, and we should try to do so as we write it. Don’t make it an afterthought — too often businesses make documentation a thing that isn’t done until everything else is done, this is bad. This creates a system where we not only have no idea how to use something, but we have to look at the source-code to understand it.
Recently, my friend Chris mentioned that he read the following statement from Google themselves in regards to Android:
Even the best developers frequently make mistakes in the way they interact with the Android system and with other applications
This is a very true aspect of Android development, and after thinking about it, I think we can blame the documentation.
Let’s be realistic, there’s hardly every a “bad system”, there’s mostly “bad usage” of the system, often encouraged by some sort of failure in the documentation:
- Missing information on how to properly use an API;
- A complete lack of examples on usage;
- No explanation of how something works, simply examples;
- Out-of-date documentation, such as in regard to Rev A, when we’re on Rev L;
- A lack of organization (a sane person expects A.B to be under A, but it’s actually under C);
- Too much documentation, more a “word problem” than anything else;
I’m going to use the Android documentation as an example here, because it really falls into the latter category which is possibly the biggest issue you can have. As people, we take the path of least resistance (go figure, so does electrical energy, water flow, air flow, basically everything ever). If we need to go from A to B to C, we do that. If D is optional, and it’s out of the way, we probably won’t go. It’s human nature, we are designed to take the easiest, quickest or most effective path.
When it comes to documentation there’s a “sweet middle”, you can have too little, and you can have too much. Both of those are dastardly: in the first case the software cannot be understood, in the second it probably won’t be understood. As an example of how documentation harms, let’s look at the Android API documentation.
There’s no immediate call to action to the documentation
When you first hit this page it leaves you wanted to know how and where to go. I want to know how to get a location via GPS, how the hell do I navigate to it? For those who want the answer, it’s:
- Click “API Guides” on the left bar (probably in a new spot by the time you read this)
- Location and Sensors
- Location Strategies
We have two problems here: first, I would not expect GPS information to be under “Location Strategies”, I see “Position Sensors” and gravitate there. Second: this page gives you a plethora of information, too much information, in fact. I came looking for a sample of gathering the GPS location, what I got was a bunch of word-problems, and a massive block of code that, without context, really only tells us how to determine if a location is better or not. What we need to do is really read into “Deciding when to start listening for updates”, as this tells us how to hook the GPS Location provider to our code.
It’s been a while since I’ve dug into the Android documentation, but that took me 30 minutes to find. You know what’s easier? Google: android get gps location, first result for me is Stack Overflow with a great, and brief, explanation. Realistically, Google could have given us a “cliff-notes” version that was equivalent to this Stack Overflow post. But they didn’t — instead we had to put in a significant amount of effort to find it, and it’s not in the spot we would expect. Too much documentation, and it’s disorganized. Without reading paragraph after paragraph (many of which are details irrelevant to getting the location) we really won’t get an answer from the documentation.
Documentation is always an afterthought
I’ve been in the industry a while, and I’ve never come across a situation where documentation was a priority. It’s always an afterthought. Even in languages like F# where the majority of the hard work is done by a single /// comment, it’s still an afterthought.
The problem with almost every single documentation system out there is that it’s not written by the person who wrote the code. We often have technical writers (who often still have very good skills in programming) write the documentation — most of the time they’re just as good at writing software as any developer, but they choose not to. They instead write documentation, the problem being they didn’t write the code, so they’re writing documentation based on what they can read of the code. Anyone who is a developer knows that reading even simple code written by another developer is often very difficult. It’s a hard thing to do — and it’s largely because it requires complex thought processes. I don’t think the same way as you, and you don’t think the same was as the technical writer, so by the time our code gets that far down the line no one really knows what it does, unless we commented or included documentation.
It usually takes 10-30 seconds to write documentation for a function, property, class, whatever. It’s usually really quick, and it provides a plethora of knowledge afterwards. It really helps create a much more pleasant environment to work in.
If you overdo it (as in the case of that article), I’d suggest finding a better way to write it. You can reorganize it, and for the curious few include a “for more information on <thing>, click here.” That simple — you keep it concise for the consuming developers, and don’t leave out important information.
So what can you do to improve the situation?
Well I already mentioned writing documentation about whatever “thing” you created, document what the function does or what the property means. But it’s more than that — if you see documentation out there that is bad, build a better version. Help improve, create the documentation you needed.