Well, yes. Documentation. You know that you have to write it for your code, but you never write it, because it's soo boring. And when you have to deal with other's code, you blame them for not writing the documentation.
Well, if you are still here, that's what I wanted to say. There are many huge projects done by serious companies with lots of the documentation. And it's clear that they spent lots of time on documenting all and every public function. But still they are doing it in a wrong way! Lots of documentation is not great by itself!
There's so many times you see the detailed explanation of functionality having no idea how does it apply to your case. The latest example for me was the Google Web Toolkit documentation. It's kinda big and has all kinds of tutorials and articles. It gives you step by step guide for creating a working project. But still it gives no idea, if that's what you wanted or how GWT is designed to be used. Or how it works inside.
Not only it applies to the general questions. It's the same in details. GWT basic term is "the module". But what is "the module"?? Did the previous link help you to understand? Or did glossary help? Well, I understand something, but I need to know, for example, if I need one "module" or more for my project? No idea. And I'm not the only one. Things are kinda better for the Google AppEngine, but still you'll get hit if you want to know how to store your data.
No reason to think that it's only Google who does this. Others are even worse. For example the documentation for the console I'm currently doing games for is a total disaster. What you get is the description of the low-level guts and registers and then a ton of doxygen-like SDK functions descriptions. Totally unrelated one to another.. Though I have been working with this platform for years, I still have no clear vision on how it works..
Come on! This book has been written in 1988! And yet you get a Hello world-like example plus lots of sparse articles as a documentation from Google!
If you want to master something, you need to understand how this 'something' works. There's no other way. You don't need to know all the details, that's true, that's what abstraction is about. And when it comes to abstraction you should know what price you pay for it. This is again impossible without understanding the underlying idea.
So when writing the documentation, first deliver the conceptual model or the general idea. Please!
The best example of things done right that I can remember is the Berkeley Database JE documentation. The Getting Started guide tells you what BDB JE does, and how would you want to use it. It even explains two different ways for you to use it. And the whole document is logically structured, so you will want to read it whole. When you understand the general idea, you can read other docs, like transactions usage explanation, or refer to the API javadoc. Which is also not just a regular javadoc you would expect. It's crafted to explain the underlaying details of the API implementation which would affect you as an API user. And it also explains use cases for the API.
Surely these docs are not the perfection, but I wish I had docs of the same quality for every API I ever use.
OK, all clear, next post please.
Well, if you are still here, that's what I wanted to say. There are many huge projects done by serious companies with lots of the documentation. And it's clear that they spent lots of time on documenting all and every public function. But still they are doing it in a wrong way! Lots of documentation is not great by itself!
There's so many times you see the detailed explanation of functionality having no idea how does it apply to your case. The latest example for me was the Google Web Toolkit documentation. It's kinda big and has all kinds of tutorials and articles. It gives you step by step guide for creating a working project. But still it gives no idea, if that's what you wanted or how GWT is designed to be used. Or how it works inside.
Not only it applies to the general questions. It's the same in details. GWT basic term is "the module". But what is "the module"?? Did the previous link help you to understand? Or did glossary help? Well, I understand something, but I need to know, for example, if I need one "module" or more for my project? No idea. And I'm not the only one. Things are kinda better for the Google AppEngine, but still you'll get hit if you want to know how to store your data.
No reason to think that it's only Google who does this. Others are even worse. For example the documentation for the console I'm currently doing games for is a total disaster. What you get is the description of the low-level guts and registers and then a ton of doxygen-like SDK functions descriptions. Totally unrelated one to another.. Though I have been working with this platform for years, I still have no clear vision on how it works..
Provide a good conceptual model.
A good conceptual model allows us to predict the effects of our actions. Without a good model we operate by rote, blindly; we do operations as we are told to do them; we can't fully appreciate why, what effects to expect, or what to do if things go wrong.
Donald A. Norman
Come on! This book has been written in 1988! And yet you get a Hello world-like example plus lots of sparse articles as a documentation from Google!
If you want to master something, you need to understand how this 'something' works. There's no other way. You don't need to know all the details, that's true, that's what abstraction is about. And when it comes to abstraction you should know what price you pay for it. This is again impossible without understanding the underlying idea.
So when writing the documentation, first deliver the conceptual model or the general idea. Please!
The best example of things done right that I can remember is the Berkeley Database JE documentation. The Getting Started guide tells you what BDB JE does, and how would you want to use it. It even explains two different ways for you to use it. And the whole document is logically structured, so you will want to read it whole. When you understand the general idea, you can read other docs, like transactions usage explanation, or refer to the API javadoc. Which is also not just a regular javadoc you would expect. It's crafted to explain the underlaying details of the API implementation which would affect you as an API user. And it also explains use cases for the API.
Surely these docs are not the perfection, but I wish I had docs of the same quality for every API I ever use.
 |
| Coffeepot for Masochists, from the cover of The Design of Everday Things |
Yeah, unfortunately, not every good software has a good documentation. To my mind there are two reasons why we have bad documentation in some projects.
ReplyDelete1. Creating documentation is as hard and difficult as creating software itself. It takes enormous amount of human and time resources. One must design its structure, divide in articles and, the most important, describe the software for unfamiliar person. It is very difficult to do when the software has been on your mind for past years.
The best API documentation I've ever worked with is Nokia Qt Documentation. As far as I know they have a special documentation team. And rumors say that there is a person who is responsible hyperlinks. Imagine that? A full-time position with, I'm sure, a significant salary just for managing hyperlinks in documentation. This is the way great things are done!
2. It is impossible to make a good documentation for a developing project. I think that's why GWT is as you described. When API changes from time to time there is no point in keeping documentation up to date. You'd better create good documentation once when the API is fixed.
I do agree that it is really difficult to create good documentation. But the main point of my whining here is a bit different.
ReplyDeleteFirst I believe, if Nokia can afford a whole documentation team for Qt with a guy responsible for hyperlinks, then Google can afford much more.
What puzzles me is that they spend time to write the documentation in the current way. I mean they do have a lot of documentation, but it's sparse and it does not give the general idea of how GWT (or GAE, or WTF) works, or how it's intended to be used. No big picture, just "Hello world" and lots of API descriptions and disconnect articles. Go figure the whole picture yourself.. I mean, if they spend time to write bad docs, it would be better if they use this time to write good docs!
Next, regarding writing documentation for a developing project. There's a point in what you say, but it mostly applies to some perfect world I think. See, there's no such moment when a big middleware project like GWT or Qt is completely finished so one can write a full docs. (Actually there is such point - when the project is dead, but at that time nobody would care about docs.)
As they published the project and they expect people to use it, then they should care about these people. That's what I think. Being not "final" does not prevent Qt or BDB JE teams from having solid docs, right?
Maybe Google can't write good doc because Nokia hired everybody who can do it well. :)
ReplyDeleteThe first release of Qt was in 1992. I don't know what was the documentation quality in, say, 1994. But for these 20 years they have had enough time to create their good doc. GWT's lifetime isn't as long. So maybe its good times are still coming...
Seems there's a deeper reason for the problem:
ReplyDeletehttps://plus.google.com/112678702228711889851/posts/eVeouesvaVX
"I'm just frankly describing what developers.google.com looks like to an outsider. It looks childish. Where's the Maps APIs in there for Christ's sake? Some of the things in there are labs projects. And the APIs for everything I clicked were... they were paltry. They were obviously dog food. Not even good organic stuff. Compared to our internal APIs it's all snouts and horse hooves."