During my workout this morning I read a couple of Paul Graham’s essays. I particularly liked the one entitled “Is It Worth Being Wise“. Here is a quote from that essay:
People whose work is to invent or discover things are in the same position as the runner. There’s no way for them to do the best they can, because there’s no limit to what they could do. The closest you can come is to compare yourself to other people. But the better you do, the less this matters.
- Paul Graham
I get a free subscription to Visual Studio Magazine. I had to do one of those online renewal things for the magazine just now and thought this was pretty funny:
Visual Studio Magazine may soon be offered in an optional digital format. A limited number of digital issues will be available for distribution.
What’s the problem with this? How can the digital issues be a limited number? Are they going to run out of bits? Can their email system only send out so many emails before it just stops working? “Get yours today! Only 500 copies of this .pdf file will be made.” Ha ha ha!
Last night I said goodbye to my old PowerMac 6100. The thing stopped working a long time ago and it has been gathering dust in my basement ever since. It was a good Mac–the second computer that I owned. (The first was the Mac SE/30.) So even though it would not boot up, it was still a sorrowful parting. The first few years I used the 6100 for lots of stuff: personal data, development, etc. Then eventually it was replaced as my primary computer by a G3. The 6100 was then re-tasked as an Oracle database server. It served me well for many years and deserves a place in my computing hall of fame as a great computer.
So much technical documentation that I read is poorly written, obtuse, convoluted, and often useless. So it is with some pleasure that I was recently reading the MySQL reference material.
http://dev.mysql.com/doc/refman/5.0/en/
Is it not interesting that some of the best written documentation comes not from large corporations and teams of technical writers, but rather from developers who just build really cool tools? What is it that makes this documentation so much better than other stuff? Here are a few thoughts:
- The content is well organized. I could very easily figure out where to look for answers to particular questions.
- The structure is easy to navigate. It was easy to figure out where I was and how to get back to something if I needed to look it up again. In contrast, I’ve also been reading some other, completely unrelated documentation where I am continually getting lost. “Where am I? How did I get here? Where was that table that I just saw yesterday?”
- The documentation provides lots of clear and concise examples.
- The documentation is thorough. I was able to find answers to all my questions. But at the same time, I didn’t need to read everything about the product.
- I find it interesting that the documentation includes user comments.
- In the end, the best documentation is that which is functional, not fancy.
I have been reading Object-Oriented Design by Peter Coad and Edward Yourdon. I was surprised to find a chapter about “Designing the Human Interaction Component”—surprised because user interface design and OO design aren’t usually covered in the same contexts. Anyway, some good criteria are given for good UI design:
Consistency. Use consistent terms, consistent steps, and consistent actions.
Few steps. … Minimize the time needed to get meaningful results…
No “dead air”. … meaningful, timely feedback is a must.
Closure. Use small steps, leading to a well-defined action.
Undo. Humans make mistakes. And humans are used to undoing—at least some of them…
No memory In “human RAM”. … Program the computer, not the person. …
Time and effort to learn. Keep it short. …
Pleasure and appeal (look and feel). Humans use software that is fun to use. Humans will tolerate other software, but only if and while they must.
- From page 63 of Object-Oriented Design by Coad and Yourdon.
“I think it quite likely that team-based creative activities such as software development are chaotically sensitive, meaning that a tiny perturbation can cause an arbitrarily large effect.”
- Alistair Cockburn in Agile Software Development, page 293
“Teamwork is often an overused word and an underutilized idea. Many people talk teamwork and working together, but when words turn into actions, the thrust is for individual tasks to ensure accountability.”
- Lientz and Rea; Project Management for the 21st Century (page 126)
I enjoy reading about different software development methodologies and practices. But in the end I’m beginning to think that more important than the particular methodology is the people. Are they good at what they do? I like this quote by Alistair Cockburn in Agile Software Development, page 264.
“Remember, success is not generated by methodology magic nearly so much as by giving people what they need to get their work done.”