[Geowanking] Bad news for those who wanted to see location-based apps on the iPhone...
bthoen at gisnet.com
Sat Jan 27 09:10:03 PST 2007
On Sat, Jan 27, 2007 at 02:49:53PM +0000, Andrew Larcombe wrote:
> stephen white wrote:
> >it's the
> >simple fact that open source software sucks dead dogs balls when it
> >comes to the basic essentials like polish, presentation and documentation.
> You're putting the cart before the horse
> basic essentials != polish, presentation and documentation.
> the basic essentials = correct functionality
> polish, presentation etc = nice additions, but not critical.
Writing as a recent *user* of open source geo-mapping and database tools, I'd
argue that good documentation IS a "basic essential". The projects that
can't muster the energy or ability to get good documentation written
seldom get off the ground.
But I also develop software in my day job, and so I've wrestled with
this problem too. At one extreme there's the artist hackers who say,
"Documentation? The source code speaks for itself." The other extreme
seldom gets realized because the further you get from the self-documenting
source code, the more difficult it is to "refactor" in-line comments,
scattered programmer's notes, and formal write-ups aimed at several different
audiences. The problem is that different people with different needs look
at a software project with different intentions and abilities.
If software is going become popular, it must not only do the job it was
designed to do but it also has to be able to allow potential developers,
integrators, consultants and end users to understand it from their current
perspective. For example, a developer wants to be able to move through the
source at different times with different points of view. Sometimes you want
to follow a function's logic line by line, but then you want to follow the
logic of its context in relation to its module of functions, and up through
higher levels of abstractions.
The knowledge abstraction process continues up past the user interface too.
Typically at this level you start to see Users Reference guides and Users
Manuals (the first is more of a dictionary or encyclopedia used to look up
facts, while the other is the novel that could and should be read cover to
cover that describes how to do the high-level tasks.)
Writing all that and managing to transfer the appropriate amount of
knowledge using all the different voices required to reach all the
different audiences, as well as keeping it in synch with the reality shaped
by the source code, is very, very hard. Expensive too.
If your software is ever going to be embraced by a large user community and
you don't have a marketing department like ESRI's or Microsoft's, then you
HAVE to make the additional effort to include good documentation.
But do you really want something like "commercial success" for your open
source software? While I still think that good documentation is essential,
I don't think that writing commercial-grade documentation is a good goal
for an open source project. It might be a good thing that open source
software is not easy to "mass market". It might be a good thing that a user
needs to work a little bit to understand a package. It might be a good
thing that he or she will need to join an on-line users forum to learn the
lore as passed down from experience.
- Bill Thoen
More information about the Geowanking