How to use Python well?

[Roy Smith]

In article <slrnilu2e0.15e.grahn+nntp at frailea.sa.invalid>,
 Jorgen Grahn <grahn+nntp at snipabacken.se> wrote:

> On Thu, 2011-02-17, Roy Smith wrote:
> > In article <slrnilr5lj.15e.grahn+nntp at frailea.sa.invalid>,
> >  Jorgen Grahn <grahn+nntp at snipabacken.se> wrote:
> >
> >> - Write user documentation and build/installation scripts. Since I'm
> >>   on Unix, that means man pages and a Makefile.
> >
> > Wow, I haven't built a man page in eons.  These days, user documentation 
> > for me means good help text for argparse to use.
> 
> Perhaps I'm old-fashioned, but all other software I use (on Unix) has
> man pages. I /expect/ there to be one. (It's not hard to write a man
> page either, if you have a decent one as a template.)

The nice thing about help text is that it keeps the documentation and 
the code in one place, which makes it a little more likely people will 
actually update the docs as they update the code.

> I guess you're working within an organization?

FSVO "organization", but yes.

> Local rules override personal preferences -- if everyone else is 
> using the wiki, I guess you must do too.

I've become very enamored of wikis because of the lost activation energy 
barrier and instant feedback.  To update a man page (info node, etc), 
you need to find the source document, perhaps check it out, edit it, 
submit it back to version control, install the new version in /usr/man, 
and so on.  People tend not to bother.  Wikis are so much more 
lightweight, they're that much more likely to get kept current.

> I have to say though that *not* handling the documentation together
> with the source code is harmful.  If source code and documentation
> aren't in version control together, they *will* go out of sync.

That is a valid argument against wikis.