On Feb 4, 8:05 am, Felix Schwarz <[EMAIL PROTECTED]> wrote:
>
> IMHO the "good docs" thing is nothing which can be achieved by stopping
> developing. First of all, it depends on people actually doing something. If
> there not enough documentation writers, maybe the current documentation is
> "good
> enough" for most users?
>
> I think its the same as "I want bug free software. All developers should only
> fix bugs. In order to get all bugs, we have long freeze periods." This does
> not
> work out for most open source projects.
>
> However, to get better docs, it should be easier for users to add
> documentation.
> Many sites in the wiki are locked down and the comment field is much too
> small
> to add a complete paragraph. More often than not I find interesting docs in
> the
> old trac wiki - there are many interesting snippets. Maybe because anyone
> could
> add his/her notes?
I would take the view that the TG docs might be good enough for most
present users if only due to the fact that many look at the state of
the docs and the attitude of the project towards the documentation...
shake their heads... and move on to something better.
It has nothing in common with "wanting bug free software". It might
have something in common with "wanting software with few and innocuous
enough bugs to be usable by most users".
I'm seeing a lot of "It's hard to get people to write docs" and
"that's just the way it is in open source", and "maybe the
(nonexistent) docs are good enough" attitudes.
And its all a big cop out. Look at Django's docs. Look at Rail's
docs. While you're at it, look at Apache's docs, MySQL's docs,
PostgreSQL's docs, Squid's docs, PHP's docs, Python's docs, Ruby's
docs,.
These projects are doing something right... and *all* have more users
than TG, in large part because of good documentation and a stable API.
It is *NOT* the users' responsibility to write the reference
documentation. And it is *very* inefficient to do things that way.
The one who understands the API the best is the one that wrote the
code... at the time that he wrote it.
Not providing proper documentation along with patches and tests is
most un-Pythonic. It violates the spirit, if not the letter, of "The
Zen of Python". And accepting patches into *Trunk* without suitable
documentation tickets is a mistake... as TG 1.0 has demonstrated all
too clearly (and is also most un-Pythonic).
I've heard it said that 2.0's docs will not have this problem because
it's building on the 1.0 base. OK. Where are the draft reference
docs for ToscaWidgets?
As a user who has been observing this situation for coming up on a
year and a half, I think it is time for the project to look at what it
is doing wrong. Look to the many other successful projects that *do*
manage to have good, even great, docs, and see what it is that they
are doing differently that has contributed to their success on that
front.
I believe that it is, at the very least, going to require a change in
the patch submission rules. (And for the changes to actually be
enforced! No matter how cool the feature might be!)
Something is required that is more effective than "If it's not
documented we won't claim it as a feature (nudge, nudge, wink, wink)".
Because that has not worked.
The problem *is* soluble... *if* the project really cares.
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"TurboGears" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/turbogears?hl=en
-~----------~----~----~----~------~----~------~--~---
