stale doc files #421

New Issue

zooko · 2008-05-29T22:27:27Z

zooko commented

2008-05-29 22:27:27 +00:00

I've been noticing stale doc files or wiki pages. Here is a partial list. I'd like to go through these and either delete them, update them, or replace them with a reference to the new replacement doc.

FileEncoding on the Doc page
ShareEncoding on the Doc page
PeerSelection on the Doc page
ChangingFilesWhileCopyingThem on the Doc page
source:docs/install-details.html and source:README.w32 has lots of carefully gathered notes about building and installing on various platforms, but some of it may be obsolete, and all of it is very badly formatted and organized
source:roadmap.txt

I've been noticing stale doc files or wiki pages. Here is a partial list. I'd like to go through these and either delete them, update them, or replace them with a reference to the new replacement doc. * [FileEncoding](wiki/FileEncoding) on [the Doc page](wiki/Doc) * [ShareEncoding](wiki/ShareEncoding) on [the Doc page](wiki/Doc) * [PeerSelection](wiki/PeerSelection) on [the Doc page](wiki/Doc) * [ChangingFilesWhileCopyingThem](wiki/ChangingFilesWhileCopyingThem) on [the Doc page](wiki/Doc) * source:docs/install-details.html and source:README.w32 has lots of carefully gathered notes about building and installing on various platforms, but some of it may be obsolete, and all of it is very badly formatted and organized * source:roadmap.txt

zooko added the

labels 2008-05-29 22:27:27 +00:00

zooko added this to the 1.1.0 milestone 2008-05-29 22:27:27 +00:00

warner commented

2008-05-29 22:47:42 +00:00

I will remove the first four docs (FileEncoding, ShareEncoding, PeerSelection, and ChangingFilesWhileCopyingThem) from the wiki pages, and put their contents (whatever remains accurate and relevant) into the source tree in source:docs

We're going to try to put long-term docs in the source tree, and use the mailing list for discussions (rather than using wiki pages for discussions).

I will remove the first four docs (FileEncoding, [ShareEncoding](wiki/ShareEncoding), [PeerSelection](wiki/PeerSelection), and [ChangingFilesWhileCopyingThem](wiki/ChangingFilesWhileCopyingThem)) from the wiki pages, and put their contents (whatever remains accurate and relevant) into the source tree in source:docs We're going to try to put long-term docs in the source tree, and use the mailing list for discussions (rather than using wiki pages for discussions).

warner commented

2008-05-29 22:48:22 +00:00

docs/install-details.html and README.w32 are now covered by #194, and are removed from this ticket.

warner commented

2008-05-29 22:50:57 +00:00

I will make sure there is a ticket present for everything in roadmap.txt, and then delete roadmap.txt

warner commented

2008-05-30 00:53:38 +00:00

Hm, it's actually kind of nice to have the HTML docs for this stuff, because
then the pictures and the text are on the same page.

Having the docs in source:docs/ makes them more likely to be updated, though.
I'll start by updating the docs in the wiki.

What needs updating:

FileEncoding: we no longer use a fileid. When CHK is used, the encryption
key is computed with a convergence secret, and we use SHA-256d. The
encryption key can also be random instead of using CHK. The "verifierid"
is actually the flat ciphertext hash, which is a small (and optional)
component of the UEB block. Encoding and share merkle trees work as
described.
ShareEncoding: this is actually just a placeholder for a link to a FEC
page, and should be moved to the [Bibliography]Bibliography
PeerSelection: this page is still accurate. The PeerSelection/TahoeTwo
page that it points to needs small updates (but should be moved to
source:docs/): replace "verifierid" with "storage index".
ChangingFilesWhileCopyingThem: this just captures some early design
discussion. I'll turn this into a ticket.
roadmap.txt: this should be split into individual tickets, and the
file then removed from the source tree

Hm, it's actually kind of nice to have the HTML docs for this stuff, because then the pictures and the text are on the same page. Having the docs in source:docs/ makes them more likely to be updated, though. I'll start by updating the docs in the wiki. What needs updating: * [FileEncoding](wiki/FileEncoding): we no longer use a fileid. When CHK is used, the encryption key is computed with a convergence secret, and we use SHA-256d. The encryption key can also be random instead of using CHK. The "verifierid" is actually the flat ciphertext hash, which is a small (and optional) component of the UEB block. Encoding and share merkle trees work as described. * [ShareEncoding](wiki/ShareEncoding): this is actually just a placeholder for a link to a FEC page, and should be moved to the [Bibliography]Bibliography * [PeerSelection](wiki/PeerSelection): this page is still accurate. The [PeerSelection](wiki/PeerSelection)/TahoeTwo page that it points to needs small updates (but should be moved to source:docs/): replace "verifierid" with "storage index". * [ChangingFilesWhileCopyingThem](wiki/ChangingFilesWhileCopyingThem): this just captures some early design discussion. I'll turn this into a ticket. * roadmap.txt: this should be split into individual tickets, and the file then removed from the source tree

warner commented

2008-05-30 01:12:49 +00:00

ShareEncoding: removed
ChangingFilesWhileCopyingThem: turned into ticket #427

PeerSelection: actually, this could be useful from a historical perspective: it explains paths we didn't go down. Should such things be put into source:docs ? Or on a wiki page?

[ShareEncoding](wiki/ShareEncoding): removed [ChangingFilesWhileCopyingThem](wiki/ChangingFilesWhileCopyingThem): turned into ticket #427 [PeerSelection](wiki/PeerSelection): actually, this could be useful from a historical perspective: it explains paths we didn't go down. Should such things be put into source:docs ? Or on a wiki page?

warner commented

2008-06-03 01:44:11 +00:00

ok, PeerSelection is gone, and moved into the source tree in source:docs/historical/

ok, [PeerSelection](wiki/PeerSelection) is gone, and moved into the source tree in source:docs/historical/

warner commented

2008-06-03 03:00:07 +00:00

and FileEncoding is gone. The only thing left to this ticket is roadmap.txt .

and [FileEncoding](wiki/FileEncoding) is gone. The only thing left to this ticket is roadmap.txt .

warner commented

2008-06-03 05:30:25 +00:00

..and roadmap.txt is gone, split into a bunch of separate tickets (mostly in the #444 to #451 range). This ticket is now done.

warner added the