How to use Python well?
roy at panix.com
Sat Feb 19 01:20:58 CET 2011
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.
More information about the Python-list