Documentation Strategy

Jump to bottom Edit New page

andychu edited this page Jun 20, 2019 · 8 revisions

TODO:

Document our strategy for writing good docs!
Maybe: look at how Python / PHP, etc. do it. People seem to really like PHP docs, which help them with a confusing language.

Inputs

Human-written text
builtin signatures from osh/builtin.py, etc.
? ... Test cases ... ?

Outputs

help builtin (following bash)
HTML for the website
man page (mdoc) @msingle is working on this.
Docstrings and flag description can be displayed in completion as well!

Other

This wiki! I like it for drafting material that may go into "official" docs.
doc/osh-manual.md and doc/known-differences.md
- These are not published anywhere yet. Should have a script to dump them on the website for every release?

Related

I use build/doc.sh update-src-versions on every release
The top of devtools/release.sh shows the release process. A version of this tree of HTML is built every time.

Philosophy

... Have a single point of truth, but don't go overboard. i.e. I think the Python project believes in "separately-written docs"?