Build and editing instructions

Narrative

I started to work on this tree. Obviously I wanted to build the thing. So I looked at the top-level README.md, But it contained no build instructions, just links to sub-parts.

So I read .gitlab-ci.yml, knowing that would certainly tell me how to build the thing. After I had found the build scripts I did a git grep to see if there was any existing information. I them buried under an inappropriate heading in a 17-paragraph essay in spec/README.md. IMO the build instructions ought to be in the toplevel.

Having built the document I started to work on one of the files. I found a source file I wanted to edit (spec/rend-spec/index.md) by nagivating the source tree (that was easy). When I had edited it I ran the build. Then of course I wanted to look at my modified file.

I used the list of sections in the top-level index.html since that looked like a table of contents. (Note: the top-level index.html seemed like an unworkable wall of text to me, so I didn't read any of the words.) So I visited the link in the table under /rend-spec. On my screen it showed as being a link to "(Tor Onion Service Rendezvous Specification", so I clicked on that.

I then wasted about 15 minutes trying to figure out why none of my changes were appearing in the output document. Eventually a grep -R of the output told me that the text I was seeing wasn't present in my output html/ directory, and I twigged that I had followed a link to the official rendered site.

I also noticed that we recommend that people read the mdbook manual before starting work. IMO people should not read the mdbook manual before starting to edit these files. That's a waste of their time. We should link to the manual so that they can look things up when they need to, but most editors can be oblivious of the content of that manual.

I am filing this as a ticket since (i) I wanted to share my experience (ii) I think a big reorganisation of all this is warranted, which probably ought to be discussed

My opinions

• spec/READE.md is confused about whether it's the readme for the specs, or for the whole tree. I firmly believe that the toplevel index.html should be built fromk the toplevel README.md.
• The specs/ front page should start with structured, critical information, including a table of contents, document status (briefly!), and cross references. Most of the text in specs/README.md should be in a subsection, or even a completely different file. The parts that apply to the whole tree shouldn't be under specs/.
• There should be one link to the official versions, somewhere prominent (probably one at the top of the rendered specs/ as well as one at the top-level index.html. All other internal links should go to the locally built version.
• The toplevel document should contain the build instructions.

Next steps

I am happy to make the changes I propose but I suspect it may be controversial and/or disruptive.