Negative feedback

[Dan Jacob]

Just read the post http://lion.taoriver.net/?p=10 which gives some
quite negative feedback about TurboGears. I think he has some valid
points about documentation: it's perhaps given the impression that TG
is already very easy to get up and running even for (python/web app)
novices, and maybe some info (like standard template variables) needs
further explanation.

Of course TG is still bery much in its infancy, but is this something
that visitors to the site should be informed of ?

[David Stanek]

We probably should let users know that things are moving very rapidly, but not at 100% yet. But the two things the user struggled with were somewhat cherrypy related.

-- David

[bon...@gmail.com]

I believe that depends on the expectation of the user. I find
TurboGears fits my expectation nicely and I don't think it is in its
infancy. It is quite an usable framework, even at its 0.5 stage.

It is not what Visual.Net/ASP.net provides(which for first time web
developer is much easier but a nightmare as the things got complex).

[Elvelind Grandin]

I think the first problem he had (not finding how to get the full
url), is perhaps due to the fact that that info does not exist on the
turbogears page, instead there is a link to cherrypys site. perhaps we
need to think about including some docs for cherrypy on the turbogears
page instead. Even more so when the docs at cherrypy isn't the
greatest in the world.

--
cheers
elvelind grandin

[David Stanek]

On 12/28/05, Elvelind Grandin <elve...@gmail.com> wrote:

I think the first problem he had (not finding how to get the full
url), is perhaps due to the fact that that info does not exist on the
turbogears page, instead there is a link to cherrypys site. perhaps we
need to think about including some docs for cherrypy on the turbogears
page instead. Even more so when the docs at cherrypy isn't the
greatest in the world.

Would it be better to enhance the CherryPy docs to suit what our user's need? That way the information only has to live in one place.

-- David

[Elvelind Grandin]

Yes, that a good point. The problem is that the user still needs to
figure out if the solution to there problem is in CP, turbogears or
some other module.
Unified docs would solve that problem

--
cheers
elvelind grandin

[Jorge Godoy]

Elvelind Grandin <elve...@gmail.com> writes:

> Yes, that a good point. The problem is that the user still needs to
> figure out if the solution to there problem is in CP, turbogears or
> some other module.
> Unified docs would solve that problem

How are these docs written? XML? LaTeX? Using docstrings? Having them
"fixed" on CP's docs and mirroring the desired parts to TG's website seems to
be the best thing to do.

--
Jorge Godoy <jgo...@gmail.com>

[Elvelind Grandin]

I belive that they use docbook.
And yes. mirroring them (automaticly or manually) is probably the best way.

>
> --
> Jorge Godoy <jgo...@gmail.com>
>

--
cheers
elvelind grandin

[Kevin Dangoor]

Thanks for the link, Dan.

Maybe the "Need help?" sidebar that appears in "Community" (which was
"Support' once upon a time) needs to move to the docs page.

I just posted a comment on Lion's blog. I certainly agree about the
doc issues, but I also think he didn't give the community a fair
shake.

Kevin

On 12/28/05, Dan Jacob <dan....@hotmail.com> wrote:
>

--
Kevin Dangoor
Author of the Zesty News RSS newsreader

email: k...@blazingthings.com
company: http://www.BlazingThings.com
blog: http://www.BlueSkyOnMars.com

[Kevin Dangoor]

On 28 Dec 2005 11:17:07 -0200, Jorge Godoy <jgo...@gmail.com> wrote:
>

Jared and I have talked about interesting ways to generate the table
of contents (or even multiple tables of contents for different
audiences) for the docs section of the site. Breaking out the CherryPy
docs this way seems valuable. Since they're XML, that gives us some
nice options. (We've also talked about breaking up the Getting Started
doc similarly... this is where it's nice that the docs are all XHTML -
easy to slice and dice.)

Kevni

[Urban Škudnik]

One suggestion about doc pages.

Every doc page and all of it's sub-sections should have a place where
users (novice and more expirenced ones) could post comments with
questions or solutions to most common problems related to subject. An
example of this is zope's documentation - users can view these comments
as well as turn them off.

That way all questions related to certain subject would be in one place
and users wouldn't need to browse usergroups or search on google for
hourse.

[Frank Hale]

> Of course TG is still bery much in its infancy, but is this something
> that visitors to the site should be informed of ?

Yes, most definitely. I've been evaluating TG (translated to reading
the homepage and lurking on the mailing list) for about 2 weeks now,
having zero Python knowledge thus far. I've watched the 20 minute wiki
tutorial, pretty impressive. I have not installed TG it yet, still
waiting. From the website and lurking on the mailing list I am not
sure as to what level of usability TG has progressed to for end users.
Is it ready for general users (that would be me) or is it still mainly
for the core developers and the people that know it inside and out.

By general users I mean the people that really don't want to know how
TG works internally but instead just use it as a tool to get a job
done.

[Lion Kimbro]

I'm the writer of the blog entry.

I agree: i "didn't give the community a fair shake." The blog post,
(which I wrote in the bus, and just need to finish some things on
before I post,) basically says: "You need community engagement, at this
point, to do TurboGears. My big mistake was thinking that I could just
sit down for 13 conseutive hours, and hammer it out. In fact, at this
stage of growth, you will need to have some question-and-response time
with the TurboGears community. That means that, instead of consecutive
hours, it may be more valuable to break sessions into 2 hour blocks,
spread over some days."

So, you're quite right: I didn't give the community a fair shake.

I had come in with the expectation that I would be able to rely on
documentation alone, and just figure my way through things. That's not
the right expectation to have, and that's why I felt burned.

But, since having those questions answered, I've been having a great
time.

This next post is *positive,* and I'll leave a note here after I've
found the time to post it. (I'm at work right now.)

I would like to write a tutorial/travel-log after I'm done, that tells
about how I wrote my software, how I think beginners should approach
learning TurboGears.

It'll roughly go like so:
* part 1: downloading, installing, IRC, mailing list, expectations
* part 2: actually writing the code
* part 3: disaster strikes, you need some info: IRC, mailing list
* part 4: finishing the app, making it look nice

It'll explain what I thought were rough points, and what things worked
well- incredibly well, even.

I'd be happy to pass it by you all, first, to make sure that it's not
inaccurate.

Again: I think my primary problem was thinking that I could just sit
down with the documentation, and make an app in 13 hours.

Since TurboGears is understandably not at that stage yet, I see now
that it's better to work a couple hours every day, and ask questions
about what I'm having difficulty with. That gives this hard-working
community time to answer. And you do: My expectations have been
exceeded, in that respect. I'm amazed at how responsive you all are!

> Yes, that a good point. The problem is that the user still needs to
> figure out if the solution to there problem is in CP, turbogears or
> some other module.

> Unified docs would solve that problem.

Elvelend, yes: This was a problem I ran into many times. I was unsure
about whether something is in CP, or in TG. They're both big, and they
seem to sort of blend in with one another. So, it was very hard to know
where I should be looking.

Perhaps something that says, "For these kinds of problems, check the
CherryPy documentation. For these kinds of problems, see the TG
documentation." Of course, this assumes relatively complete TG
documentation.

I'd offer to help, but I don't think I can be much assistance; The time
it would take you to communicate to me what needs to be in the
documentation could well exceed the time it takes you to write the
documentation yourself-- a classic problem.

[Alvin Wang]

Cherrypy documentation isn't that bad. I find SQLObject to be really
incomplete. The options are documented but there are not enough
examples.

https://wiki.launchpad.canonical.com/SQLObjectGuide

It is out of date but more readable in my opinion. I may be the only
one since I know SQL much better than python.

Alvin

[vinjvinj]

what about using rest2web. Very powerful and all the doucmentation is
in text that can marked up the way you want to using templates:

http://www.voidspace.org.uk/python/rest2web/

[Michele Cella]

Great to see that now you feel more positive. :-)

You can even help to improve the documentation by submitting ticket on
the doc component, or by contributing new things to the documentation
playground (or turbogears faqs) if you feel they are needed.

http://trac.turbogears.org/turbogears/wiki/DocumentationPlayground

Ciao
Michele

[Kevin Dangoor]

Yeah, I've seen that along the way. I think our basic doc *system* is
fine (docgen.py renders out Kid templates and performs some mangling
of the XHTML files to do things like a single-page 20 Minute Wiki).
It's more about taking docs from disparate sources, bringing them
together and indexing them usefully.

We'll be diving into doc work for the 0.9 soon, I think.

Kevin

[Kevin Dangoor]

Currently, we have the "comment on this page" link that submits trac
tickets, and the documentation playground in the trac wiki. Those are
"not bad", but they require a little faster action than we've been
doing in order to keep the docs updated and answer questions faster.

I think your suggestion is a good idea for something we should
implement when the new site is up. Can you open a trac ticket for the
idea? (http://trac.turbogears.org)

Thanks,
Kevin

[Mike Orr]

Hi Lion! (We're in the same local Python group.) I've been lurking
around TurboGears for a month or so. It *is* like walking in the dark
once you get off the path, but the rate of development is so rapid
that much of it will be well lit in a couple months. It's just an
awkward time right now because there's such a wide spread between the
released and development version, and many "necessary" tools are only
in the development version and are unfinished. But the same thing has
happened with Debian and other projects, and eventually a stable
version does come out that has enough features you can write a serious
app with it. So I'd urge you to stick around even if TG isn't ready
for your apps yet, because you learn a heckuv a lot of stuff along the
way, not just about TG but about all its base projects, and their
implementation issues, and all that background info will be useful
later, no matter which framework you choose.

On 12/28/05, Lion Kimbro <LionK...@gmail.com> wrote:
> I had come in with the expectation that I would be able to rely on
> documentation alone, and just figure my way through things. That's not
> the right expectation to have, and that's why I felt burned.

Perhaps TG needs a wiki page listing what's unfinished, missing, or
hard to do, so that new users can keep this in perspective and not
keep searching the documentation for something that isn't there.

> I would like to write a tutorial/travel-log after I'm done, that tells
> about how I wrote my software, how I think beginners should approach
> learning TurboGears.
>
> It'll roughly go like so:
> * part 1: downloading, installing, IRC, mailing list, expectations
> * part 2: actually writing the code
> * part 3: disaster strikes, you need some info: IRC, mailing list
> * part 4: finishing the app, making it look nice
>
> It'll explain what I thought were rough points, and what things worked
> well- incredibly well, even.

That would be a great article. Even an ongoing journal showing what
was easy/hard, and what workarounds you made due to unfinished
features, would be valuable.

> Elvelend, yes: This was a problem I ran into many times. I was unsure
> about whether something is in CP, or in TG. They're both big, and they
> seem to sort of blend in with one another. So, it was very hard to know
> where I should be looking.
>
> Perhaps something that says, "For these kinds of problems, check the
> CherryPy documentation. For these kinds of problems, see the TG
> documentation." Of course, this assumes relatively complete TG
> documentation.

Actually, I don't think this part is that difficult. Read the
CherryPy manual and see how the pure-CP examples are structured. Then
compare them to the TG examples, and you'll see that certain things
are done in a certain way in TG but in an ad hoc way in CP. Then skim
through the TG source and you'll see that TG takes control of a few
certain aspects but mostly leaves CP untouched to do its thing. CP
provides the basic URL parsing and server, but TG imposes the MVC.
You can also trace objects through the import statements to figure out
who's responiable for what.

> I'd offer to help, but I don't think I can be much assistance; The time
> it would take you to communicate to me what needs to be in the
> documentation could well exceed the time it takes you to write the
> documentation yourself-- a classic problem.

Just listing what you find difficult is a good start. Otherwise,
people may not realize it's underocumented.

--
Mike Orr <slugg...@gmail.com>
(m...@oz.net address is semi-reliable)

[Michael Schneider]

Welcome Lion,

I too am a more of an application programmer then a web developer.
We develop CAD/CAM/CAE apps. I am looking to use TurboGears for
internal web projects.

I have done some web programming, but I am more into distributed
programming
and architecture for our 3d CAD/CAM/CAE system.

I work mostly in C++, but have used python since the early 90's for
productivity
tools to aid in development/ project release.

TurboGears have treated me well overall, and the community has treated
me very well.

I have hit a few brick walls (usually of my own makeing :-) but the
community
has bailed me out.

I have also hit some walls with Rails, so I think they are there with
any app.

I look forward to your articles.

Mike Schneider

[Leandro Lucarella]

Frank Hale, el mi�rcoles 28 de diciembre a las 14:31 me escribiste:

>
> > Of course TG is still bery much in its infancy, but is this something
> > that visitors to the site should be informed of ?
>
> Yes, most definitely. I've been evaluating TG (translated to reading
> the homepage and lurking on the mailing list) for about 2 weeks now,
> having zero Python knowledge thus far. I've watched the 20 minute wiki
> tutorial, pretty impressive. I have not installed TG it yet, still
> waiting. From the website and lurking on the mailing list I am not
> sure as to what level of usability TG has progressed to for end users.
> Is it ready for general users (that would be me) or is it still mainly
> for the core developers and the people that know it inside and out.

I think it's in some point in the middle, maybe closer to the first one,
but as any alpha software you should expect some lack of documentation
and API changes... General public can use it, but you better have an eye
on the mailing list (or at least the planet) to see what's happening and
what thing you should stop using and what things to expect in the future.

--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
.------------------------------------------------------------------------,
\ GPG: 5F5A8D05 // F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05 /
'--------------------------------------------------------------------'
De las generaciones venideras espero, nada más, que vengan.
-- Ricardo Vaporeso

[Leandro Lucarella]

Lion Kimbro, el mi�rcoles 28 de diciembre a las 11:31 me escribiste:

> I'd offer to help, but I don't think I can be much assistance; The time
> it would take you to communicate to me what needs to be in the
> documentation could well exceed the time it takes you to write the
> documentation yourself-- a classic problem.

Reporting problems is a great way to help!

--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
.------------------------------------------------------------------------,
\ GPG: 5F5A8D05 // F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05 /
'--------------------------------------------------------------------'

Hey you, dont help them to bury the light
Don't give in without a fight.

[Mike]

To Frank Hale, Lurker:

I dove into TG as a completely inexperienced web developer - my last
projects were in simple HTML, no scripting at all other than rollover
images. My current project (a photo gallery) uses only the Kid and
SQLobject components of TG so far, but I found them reasonably easy to
learn. I also had to learn Python from scratch, but found that it also
was easy to pick up (the only other programming experience I had was
with C++ from college). The Python website is a very valuable
resource, and examples are pretty easy to find elsewhere as well.

Go for it. It's worth a try.

Mike

[Lion Kimbro]

Okay!

Thanks, everybody, for all the helpful advice.

Kevin, I've posted my apology & insights on:
http://lion.taoriver.net/?p=11

I'll take Mike Orr's advice, and journal about what I find easy or
hard, what I have difficulty finding, and techniques / insights /
workarounds I figure out.

And maybe I should heed Michele, and also post them to the wiki, as
public domain artifacts?

It's hard to know where to post these days, what with blogs, mailing
lists, and wiki to decide between! But perhaps I should just
cross-post. Oh, and trac. ;)

Again, thanks everyone. :)

[Kevin Dangoor]

On 12/29/05, Lion Kimbro <LionK...@gmail.com> wrote:
>
> Okay!
>
> Thanks, everybody, for all the helpful advice.
>
> Kevin, I've posted my apology & insights on:
> http://lion.taoriver.net/?p=11

Thanks, Lion!

>
> I'll take Mike Orr's advice, and journal about what I find easy or
> hard, what I have difficulty finding, and techniques / insights /
> workarounds I figure out.
>
> And maybe I should heed Michele, and also post them to the wiki, as
> public domain artifacts?
>
> It's hard to know where to post these days, what with blogs, mailing
> lists, and wiki to decide between! But perhaps I should just
> cross-post. Oh, and trac. ;)

Here's how I'd break it down:

1) general thoughts and experiences - on your blog
2) cross post those to the mailing list as you see fit (if it's on the
Planet, many people will see it)
3) something that can act as a started document for a piece of the
system - on the wiki in the DocumentationPlayground
4) a comment or addition for a specific document - use the "comment on
this page" to put something in trac

There are no firm rules, of course... this is just what seems to fit
the various modes of communication to me...

Kevin

[Mike Orr]

Regarding absolute URLs, I'm not sure if what you're trying to build
is related to your distributed catalog-of-wikis thing. Most TG sites
are standalone and independent so relative links work well, especially
with their ability to automatically adjust to whatever URL environment
they're deployed in. But for a distributed system where every site
needs absolute links to every other, perhaps TG hasn't thought that
far. If so, showing concrete use cases will get it done.

My own experience with absolute links was with Zope several years ago.
If you inserted a dynamic link to an image object (as opposed to a
literal link); e.g., "<dtml-var my_image>", it would expand to the
absolute URL. If Apache was proxying to ZServer, that URL would be
wrong. It would be ZServer's (:8080), which you probably don't want
to advertise, and which may not be publicly accessible at all.
Apache's ProxyPassReverse would try to fix the situation by rewriting
the HTML, with some success but it wasn't perfect. Then with trying
to test sites at alternate locations, or when the DNS wasn't working
and I couldn't get to a name virtual host, I just started staying away
from absolute links altogether unless they're unavoidable.

[Urban Škudnik]

Kevin: did so - http://trac.turbogears.org/turbogears/ticket/312
sorry for quite a long time to post a ticket and to replay here
(replaying here again was a thought from my friend) - new year's eve
was quite long for me :)

[Kevin Dangoor]

New year's eve is a good thing to enjoy :)

Thanks for the ticket,