In article <slrnilu2e0.15e.grahn+n...@frailea.sa.invalid>, Jorgen Grahn <grahn+n...@snipabacken.se> wrote:
> On Thu, 2011-02-17, Roy Smith wrote: > > In article <slrnilr5lj.15e.grahn+n...@frailea.sa.invalid>, > > Jorgen Grahn <grahn+n...@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. -- http://mail.python.org/mailman/listinfo/python-list
