[Kss-devel] will megrok.kss ever go "live"?

[Brandon Craig Rhodes]

Godefroid Chapelle <gotcha at bubblenet.be> writes:

> Balazs Ree wrote:
>
>> I stole this entirely from zc.buildout:
>
> I had guessed so ;-)

Note that zc.buildout is known for traditionally having a poor
documentation "presence" on PyPI. :-) Though it has gotten better - I
see that it now has examples of useful buildout.cfg's at the top,
before it plunges into impenetrable doctests - it's bad enough that
someone just blogged about it:

   http://groovie.org/articles/2008/04/04/sacrificing-readability-for-automated-doc-tests

So we should try to make sure that the documentation for KSS, if we
copy buildout's recipe, makes more sense than buildout's horrible
series of unexplained and difficult doctests that it throws across its
PyPI page. :-)

Remember, too, that the way PyPI currently works, users can't "see"
the actual links available for download (which some people do still
use) until they make it to the bottom of the documentation.  For this
reason, I usually limit my PyPI documentation to (a) an exciting and
human-readable statement about what my package does, with one or two
pieces of Python code thrown in to illustrate, and perhaps (b) a list
of what's new in this particular version (not the whole history of the
project, which pushes the rest of the text way to the bottom of
people's scroll bars!).

The one module on earth that I myself am responsible for has PyPI
documentation that looks like:

   http://pypi.python.org/pypi/pyephem/3.7.2.3

Anyway, just a thought.

-- 
Brandon Craig Rhodes   brandon at rhodesmill.org   http://rhodesmill.org/brandon