[Grok-dev] Re: license for docs

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

daniel wrote:

> I have a question: Is there a perceived or existing difference with regards
> to this topic between what one would call "official documentation" versus
> simple fan-made how-tos?

Not that I know of.

> Can you describe how doc licensing is dividing the zope ecosystem across
> code bases? I'm not familiar with this.

The obvious split is between Plone (GPL) and Zope (ZPL):  the Plone
folks chose a license for Plone which made it impossible for the Zope
folks to use Plone components and the same terms as the Plone folks use
Zope components.  Part of that divide has been repaired, as the Plone
community moved to improving / contributing to the ZPL layers "below" Plone.

> The biggest problems I have seen
> with zope is a complete lack of documentation past the doctest level and
> even worse, no kind of organization or versioning system so that when you
> search for docs new and relevant versions can be obscured by old and
> deprecated docs.

Cleaning up the zope.org docs (including removing / hiding a lot of
antiquated ones) is part of an onging process.  I agree that doctests
are not a good place to start learning Zope:  at best, they can provide
an overview for using a given package.  There are also generated docs
which provide "reference" material, based on interfaces and docstrings:
 those docs are again not good starting points for folks unfamiliar with
the software.


> It all seems to stem from a lack of motivation from the developing
> contributors to bother with documentation rather than from a license issue.
> There may also be a general feeling by developers that the code is self
> evident enough to them so why bother. Unfortunately it becomes a nightmare
> for new users who are obviously not in the same ballpark as zope developers
> and are trying to get to know zope because it makes the learning curve into
> a cliff with no guidance on how to scale it.
> 
> As far as zope goes the only practical route for a new user seems to be to
> buy phillip's book, which is really good and I'd recommend it, however
> official documentation it is not.

You are quite correct that writing / updating the "narrative" docs is an
important task for the Zope community, and one which we have
traditionally done poorly at.


Tres.
- --
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHo1wR+gerLs4ltQ4RAlgKAJ0aEh5kyzmJmY0A2ivgYcSDx/d+7gCfQKvf
4r1ABoq/wMjCVFhPs7Z5Bog=
=MVMo
-----END PGP SIGNATURE-----