“It should be intuitively obvious…” NOT!
I sat in a meeting at AT&T in Middletown NJ in the mid-80’s and heard one of my colleagues argue against spending additional time on a manual for a tool he created for the user community. I was suggesting that he provide an introduction on the purpose of the tool and the scenarios where it could be useful. The exact quote was “It should be intuitively obvious what the tool is used for!”
That phrase stuck in my head forever. In my 30 years experience in developing software, I have gone from embedded systems to GUI desktop to web apps. In my view, communicationis the biggest stumbling block in software development. And the most disastrous mistakes are almost always linked to something that a missing piece of information was intuitively obvious. Nothing is intuitively obvious!
This blog will draw from my personal reflections on the communications issues in documentation, project management and team interaction, including ideas that might seem intuitively obvious…
3 Responses to ““It should be intuitively obvious…” NOT!”
July 16th, 2009 at: 6:28 pm
Thankfully, much of the open source community has now embraced the need for good documentation and is setting an example for everyone else to follow. These days, it is difficult to come across a moderately large open project that doesn’t maintain an extensive wiki using something like Trac or Google Code.
It’s great that not only are people becoming aware of the importance of good documentation, it has become the trendy thing to do.
This is a very interesting topic for a blog. I’m looking forward to what’s to come.
July 17th, 2009 at: 9:59 am
One of the issues to be considered is “too much documentation”. If too many obvious things are included in documentation, readers will tend to skim the documentation instead of reading it. This can be an even bigger problem. Maybe a combination of better documentation process and technology can be used to produce smart documents, users can personalize it and customize it to their needs by setting a few preferences/ options.
July 17th, 2009 at: 11:14 am
Right, granularity and organization need to be intelligently applied. That really speaks to knowing the audience, for one, and accepting that there are multiple audiences, all of whom need to have their needs met.
Tools that can filter a document or a set of documents can be useful but, once again, only if intelligently applied. And that’s work that us developers are not always keen on doing.
Thanks for both comments!
Leave a Reply