Documentation is important

Tmobile-romainuy
 So I have to admit that although I've been preaching for years that open source software needs more documentation, it wasn't really something I worried about. (Probably partially because I have a good network I can always ask when in doubt.) At least that's how I felt until I got my G1 phone.

I read manuals. I read the G1 manual in a couple of minutes. And then I really wished I had the real manual – one of those that tells you everything about your phone – when …

  • At one point in time I saw a list of wireless networks on my G1. Now it just seems to connect to one. I can disconnect and reconnect … to whichever random network it wants. Nothing in the manual. Some where on my phone has got to be an option that would show me the available wireless networks and let me select one.
  • I was trying to add shortcuts to the home screen to no avail. A quick google search told me that tapping and holding would show me the most used six apps. Nope, but it did let me add a shortcut!
  • Speaking of which, my phone does a lot of cool things that I keep accidentally discovering. Like an accidental swipe to the right showed me that the home screen is three times as big as I thought!

It's a really cool phone and it does cool things, but accidentally discovering features one by one makes me feel like I'm missing out. (Not to mention the frustration I feel when I'm trying to do something I know it can do.)

So I'm not complaining about my G1. I'm just pointing out that good documentation is a good thing.

Photo by romainguy.

12 Replies to “Documentation is important”

  1. Settings > Wireless controls > Wi-Fi Settings (the list of networks is at the bottom and you can whitelist/blacklist entries)
    This should probably still be better documented…

  2. Settings > Wireless controls > Wi-Fi Settings (the list of networks is at the bottom and you can whitelist/blacklist entries)
    This should probably still be better documented…

  3. Settings > Wireless controls > Wi-Fi Settings (the list of networks is at the bottom and you can whitelist/blacklist entries)
    This should probably still be better documented…

  4. Settings > Wireless controls > Wi-Fi Settings (the list of networks is at the bottom and you can whitelist/blacklist entries)
    This should probably still be better documented…

  5. I would counter this and say that good design is what’s important. If it needs documentation its broken.

  6. the long press is the consistant metaphore for a context menu across the OS, so long pressing on the desktop pops up the menu to add a shortcut as expected. long pressing on the home button is the one that shows you the last 6 apps you’ve run.

  7. the long press is the consistant metaphore for a context menu across the OS, so long pressing on the desktop pops up the menu to add a shortcut as expected. long pressing on the home button is the one that shows you the last 6 apps you’ve run.

  8. the long press is the consistant metaphore for a context menu across the OS, so long pressing on the desktop pops up the menu to add a shortcut as expected. long pressing on the home button is the one that shows you the last 6 apps you’ve run.

  9. the long press is the consistant metaphore for a context menu across the OS, so long pressing on the desktop pops up the menu to add a shortcut as expected. long pressing on the home button is the one that shows you the last 6 apps you’ve run.

  10. the long press is the consistant metaphore for a context menu across the OS, so long pressing on the desktop pops up the menu to add a shortcut as expected. long pressing on the home button is the one that shows you the last 6 apps you’ve run.

  11. Ah, You can add a shortcut to the desktop via Menu->Add.
    While I agree that documentation is good, it doesn’t get any simpler then that.

  12. Doesn’t sound like you need documentation, sounds like you need a UI that works. You’re certainly no luddite novice! If these possibilities aren’t apparent to you, the UI’s really missing something.
    “More documentation” never works. Two kinds of documentation:
    – “Press OK” documentation, written by someone who knows even less than you about the product, by holding the product, doing the obvious, and writing it down. You already explored all the obvious things, you don’t need someone else’s breadcrumbs.
    – “From the experts” documentation, that tries to document the parts that the experts think you won’t see immediately. Sounds better … but all these things you list here are surely “obvious” in someone’s mind, not to mention “really cool” and “super powerful” and a lot of other exuberant hacker-speak. They wouldn’t have been listed.
    But blog away about this. The plus is, lots of G1-insiders will see, and some of these problems will get fixed.

Comments are closed.