Archive of UserLand's first discussion group, started October 5, 1998.

Re: Sample code and utilities?

Author:Dave Winer
Posted:3/30/1999; 7:31:33 AM
Topic:Sample code and utilities?
Msg #:4689 (In response to 4672)
Prev/Next:4688 / 4690

Thanks to Phil for responding. I think this a "looking the gift horse in the mouth" type thing. When people upload source to a public server for everyone else to use, they could have a lot of reasons for doing it, but to me, the first best explanation is that they are being generous. I know that's where I'm coming from when I release sample source and things that aren't part of the main Frontier distribution, and sometimes I write docs that are sparse, and sometimes I write docs that are detailed and sometimes inbetween.

One possible way to approach this is to, while doing nothing to discourage all forms of source-shipping, shine a spotlight on those pieces that are especially well documented and especially useful. Instead of hitting people with a hammer, hit them with a feather. If one of your purposes is to have a lot of people use it, let's show them how to make it usable by a lot of people. And that means docs that get tweaked and users that are helpful (who appreciate the act of generosity and don't nitpick things).

Paul, I was very happy to see your XMLTR site, it was exemplary, far above the norm for any development environment, not just Frontier. The quality and thought in your work was completely evident from the docs. You also clearly have a lot of experience. Many of the people in our world are young, and are doing this stuff for the first time. Being patient is something we have no choice about, us older folk. That doesn't mean it feels good, but what choice do you have?

We could also get people to help out when something comes along that we feel has permanent lasting value. An example was Seth Dillingham's queue suite. Seth is a brilliant programmer and understands Frontier deeply. When Seth says he's getting ready to release something as freeware a lot of people, justifiably, take notice. Now, if at that time someone volunteered to spend a single week with Seth and the software, writing about it, developing samples and docs, the value of Seth's work would be much more greatly leveraged. This would create components that will still be in use in 2005, not fall into disuse.

However, it's unreasonable to expect Seth to both write great software and great docs. It's very hard to write docs about software you've written. You're coming at it from 180 degrees in the wrong direction. To have written the software you must have understood it before it existed. That's a very different point of view.

I understand this issue because I'm living it right now. I had to stop working on mainResponder a month ago so I could be in position to write the intro to the Change Notes page for Frontier 6, yesterday. It took one month for me to get enough distance to be able to write about it for people who already understand Frontier and the website framework.

I'm sure I'll have more to say about this stuff.

Dave

There are responses to this message:

This page was archived on 6/13/2001; 4:49:09 PM.

© Copyright 1998-2001 UserLand Software, Inc.