[Bese-devel] Learning UCW

[Henrik Hjelte]

On Mon, 2007-01-15 at 16:14 -0500, lists at infoway.net wrote:
> Hello again,
> 
> Well, after some going back-and-forth and with the help of the members of this list,
> I finally seem to have a stable UCW environment under OS X with SBCL.
> 
> I have been fiddling around trying to learn UCW. However, to be honest, 
> 'm disappointed at the lack of documentation and/or the steep learning
>  curve required to get going with it, so I'm back here asking for help/direction.
> 
You shouldn't be disappointed with the steep learning curve. If it was
simple and obvious you would learn nothing. I believe it is called
uncommon for a reason. If you think that you will fire up UncommonWeb
fast and easy without knowing much Lisp and expect to understand
everything in a month I think you have set your ambitions way too high.

For me learning UnCommonWeb and relearning Lisp has made me much humbler
as a programmer. I now understand that I don't know everything. I find
it refreshing to learn every day. 

> I originally started looking at many public tutorials. However, they 
> are all obsolete and don't even run in the current version of UCW, 
> so I wouldn't want to spend too much time learning something
>  that has been deprecated or that simply won't work.

If you check the number of authors mailing list you can probably guess
how large this community is. We could probably fit into an old
Volkswagen. Definitely in my Saab. So any help is appreciated, for
example in maintaining and updating the documentation there is. 

And again, you will need to spend much time learning, and things will
not always work. But things will get much better when you learn how to
get around fast in the source code with slime, how to use the debugger
and so on.

> I then started going through the example applications. They seem to 
> illustrate more functionality than any of the tutorials I found. 
> However, there is a severe lack of "explanation" bundled with the examples.

The examples and code can be documented better. Sometimes what is
obvious to the author is not obvious to everybody else, but then please
join in and improve the documentation. For example by writing down your
questions somewhere.


> I spent a lot of time going through UCW's source code documentation as 
> I read the example code. Some of it makes sense, some is not so well documented.
I think the code is documented at about the right level. You have seen
the problems with documentation, it sometimes gets obsolete. Then you
have to figure out if it is the code or documentation that is wrong. 
But maybe some areas need improvement, there are always things I don't
understand immediately when I navigate through the code. But I don't
think that more documentation in the code itself, would help me much. I
rather think that more high-level documentation would be good.

I prefer pedagogical testcases to documentation, then you can see in the
testcode how things work. 
> 
> Then, there is the notion that I see the examples make extensive 
> use of package::function within the ucw package. 
> If even the examples make such use of this, why aren't all these functions
>  publicly exported so they may be formally documented?
Probably because someone forgot or didn't bother. You only need to make
change it, darcs record, darcs send -o mypatch and send it to the
mailing list. 

> 
> You can say that I'm a new Lisper and, so far, seem somewhat comfortable
>  with the "hacking" mentality that I could always go to the source
>  to understand how things work.
Most of us are beginners. Most of us don't always understand things.

>  However, even doing so is extremely difficult in UCW because not everything
>  has comments and having to understand code makes it that much more difficult
>  when you don't really know where to look, so I end up looking at one file 
> and then have to look through n files until a simple concept may be cleared up.
If functions, methods and parameters are named properly there shouldn't
be a need for lots of comments. Understanding code is sometimes
difficult. Sometimes you get frustrated.

> UCW seems to have a somewhat active community, so I ask for anyone to 
> provide more concise direction as to how you would "welcome" a newbie into the UCW world. 
I think we answer most answerable questions prompt and fast. We answer
emails. Marco has made an instruction video. The boxset was a step to
make uncommonweb easier to start with.

> I don't mean any negative criticism in this email, if anything, 
> I just hope it's for the best so more people can join this community.
Me neither, and I sincerely hope more people join. I am no spokesperson
for this community, but I think we all agree with this.

> I'm really eager and want to start doing something productive here, 
> but I really feel my hands are tight in learning the available API 
> and overall UCW development mindset.
As said, there are many things to do and we are a little community. You
don't have to know much to start updating the documentation and pointing
out problems. 

Here are some random ideas, suitable for all levels of Lisp expertise.
You don't even have to know lisp. 
* Do tests for the example application using selenium
* Remove obsolete bits in the parenscript documentation
* Write a todo-list of documentation that need updating.
* Update the documentation. 
* Do some kind of script that automatically tests uncommonweb and its
dependencies. I looked at the python buildbot today, it can be used.

> I know there are many out there listening, just hope someone is able to respond promptly :)
> 
> Thanks again,
> Daniel

I hope you stay with UnCommonWeb! I think that most of the problems you
have come from a small community, and having too high expectations on
learning everything fast.

/Henrik Hjelte