I just came here from a link on the Python Daily URL. This doesn't really explain it for me. Sometimes when I write documentation, I try to address who the reader is and what they're used to seeing, which often means separate paragraphs (or even chapters) for the particular audience.
Myself, I use Python and Java to write (non-web) applications, and Apache + PHP to write web sites & web applications. So for me, I was basically lost by the second paragraph.
I guess you're assuming knowledge of WSGI. Maybe the introduction needs a sentence like "Before trying to understand what Paste is, you should know what WSGI is (link to a _What_is_WSGI_ document)"
Mmm... you are probably right. Right now it's really directed to people who have experience with Python web frameworks. But that should be explicit, otherwise people without that experience will just be discouraged.
IMHO a better bet will be to direct it to people with little experience. A developer experienced in python web frameworks will be less impressed, he/she will have a lot of habits acquired in the other frameworks, will be more reluctant to change and Paste has to be really really good to impress him.
A beginner caries a lot less baggage. He will give Paste 10, 20 maybe 30 min. and if in that time Paste impresses him there is a good chance he will use it.
I'm a beginner and I see "Zope Page Templates", beside the fact that I get scared by the word Zope when I look at the mini introduction to TAL I'm thinking "What the heck is this?" a beginner will see to much information, a seasoned programmer will see redundancy.
In my view Paste will be better served using something like HTMLTemplate http://freespace.virgin.net/hamish.sanderson/htmltemplate.html, it is simple, powerful and did I mentioned simple? Yeah simple, how simple? well... copying one .py file somewhere in the PYTHONPATH takes care of the installation. Using it is just as simple.
Take the beginner from A to Z, show him a quick install, a simple example, a simple but not trivial example, a complex example and of course provide value. For example if John Doe were to install Paste and instantly get a Wiki and a blog or a bliki as a bonus (complete with 2-3 nice CSS designs) all validating, RSS/Atom enabled, all the bells and whistles John Doe will be very happy, he will recommend Paste to all his friends. He might not care that is python as long as it works or maybe he just discovered python and wants to use it in everything or maybe he is like me... hateing PHP syntax.
Go after the beginners! there are a lot more of them than seasoned programmers, they might be more forgiving especially if you put up a big sign saying "Alpha" and if they can do it... seasoned programmers will have no other excuse not to at least try it.# Peter Damoc
That was my feeling too knowing nothing about WSGI... I read all 3 of your attempts to explain Paste and I think this one is much better than the ones before but still maybe not basic enough...
Maybe a bit more structure would help as well, it might be just me but some more headlines, a kind of table of contents even for an article as short as this would help. There something like "What is WSGI", "How does a server fit in", etc could fit in.
I guess an example of a specific server + paste + application (that's the way it works, is it not?) like apache + paste + ? would also show more than a lot of explaining.
I read your stuff quite frequently and always wonder how you find the time to actually do stuff and at the same time read/investigate/try in all other web frameworks and other tools... That's actually something you seem to assume from the casual reader. I do read a lot about some of the (it seems) 100s of Python web frameworks but have not been able to try one as there are so many and I am always looking for a really good solution Paste might be to get to.
Just some ideas, actually writing a good documentation and explaining what something is for all kinds of users is very difficult... (something I am experiencing myself at the moment)# Chris