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 _______________________________________________ Geowanking mailing list [email protected] http://lists.burri.to/mailman/listinfo/geowanking
