[rust-dev] Documentation

[Graydon Hoare]

Hi,

I started a conversation on IRC which I'd like to make a little more 
formal here, concerning documentation formats. It's a subtle question 
because we are generating increasing quantities of information -- and 
will keep generating more -- and I'd like to bring a degree of 
systematicity to it if possible.

We currently have the following docs:

  - A wiki on github, written in github-ese markdown
  - A tutorial written in hand-extended markdown and processed
    by hand-written javascript
  - A manual written in texinfo that generates PDF and HTML trees
  - A man page written by hand in groff
  - An API documentation tree generated by NaturalDocs, from comments
    in our library code.
  - A new 'rustdoc' tool that consumes attribute-docs and emits,
    for the moment, markdown (though it might emit something else)

This is unsatisfying in a few ways:

  - The output looks inconsistent.
  - Cross references between pieces of the docs are random, dubious.
  - There is no central index, TOC; navigation aids are disjoint.
  - There is no way to acquire a bundle of "all the docs" easily.
  - Reading formats are inconsistent; some parts can be printed or
    viewed in a terminal easily, some cannot.
  - "Building" the docs is arduous and requires almost as many tools
    as building the rest of the system.

So! I would like to come up with a "strategy" (loosely stated) that 
begins to reduce these sources of dissatisfaction. This is tricky. There 
are a bunch of technologies-for-docs and they all provide some, but not 
all, nice things we might want. I'd like to at least start by gathering 
beliefs about the importance of those things. Specifically, these are my 
concerns; how important are these concerns to the rest of you?

  - Generating single-bundle "print-like" documentation artifacts
    (pdf and epub), including internal-hyperlinks or references
    when in a non-link rendering ("see page 12").

  - Inline-editing of docs in a browser "by everyone", wiki-style.

  - Viewing in a terminal (man pages, info nodes, plaintext, querying
    the API docs via a command like "rustdoc -q foo::bar")

  - Having a very-much-like-plaintext editing format.

  - Using "the same" format for API docs and hand-written manual,
    tutorial, rationale, etc.

  - Having a simple "build" process for the docs that uses as few
    tools as possible.

I've looked at a variety of tools and to my understanding, few-to-none 
of them do all this. The *closest* I can see is 
texinfo-and-some-glue-code, but I'm amenable to argument on this. 
Markdown is a popular contender, but it seems like it's heavily slanted 
towards HTML output (and possibly wikis). Maybe that's ok? Maybe PDFs 
and "printed manuals" and such are vestigial nonsense we can consign to 
history?

Opinions welcome,

-Graydon