[tahoe-dev] conversion of docs to .rst

[Greg Troxel]

Ravi Pinjala <ravi at p-static.net> writes:

> Just now in the IRC channel, it came up that the docs living in
> version control aren't especially discoverable. Zooko suggested
> converting them to .rst format and generating HTML pages from that,
> and I volunteered to do the conversion. Does anybody have any
> objections? (Better formats available? Documentation already nicely
> formatted somewhere? That sort of thing.)
>
> Doing this would make the documentation easier to read, and hopefully
> more linkable and discoverable. If I get a few ++es from people, I'll
> go ahead and start on this.

That seems fine, but I will say that I am appalled at the modern trend
of docs mainly in wikis.   I think what we need is:

  docs in some editable form as part of the source tree

  conversion to readable forms

  readable forms present as part of installed packages

  readable forms on the web for those not installed, or later versions

(part of this opinion is based on experience using software on machines
without decent internet access.)

It sounds like what you are proposing to do fits with my rant above.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 194 bytes
Desc: not available
URL: <http://tahoe-lafs.org/pipermail/tahoe-dev/attachments/20101010/d995a9b1/attachment.pgp>