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
_______________________________________________
Rust-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/rust-dev
