Skip to content

Documentation Strategy

andychu edited this page Jul 24, 2020 · 8 revisions

Related: Oil Language Docs

2020 Progress

2019 Notes Below

TODO:

Inputs

  • Human-written text - what formatting? - Markdown, rst, something else?
  • 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!
  • Zeal/Dash (could be scraped from website)

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"?
Clone this wiki locally