Documentation Strategy

Related: Oil Language Docs

2020 Progress

• Everything is plain Markdown files git! woohoo!
  • Github renders them nicely, e.g. https://github.com/oilshell/oil/blob/master/doc/eggex.md
  • But we also have our own renderings on the site: http://www.oilshell.org/release/latest/doc/eggex.html
• I open sourced all of the doc toolchain in doctools/
• Lots of tasks left!
  • help builtin
  • writing Python code to keep the source code and docs in sync
  • "advocacy" and promotional docs. See #blog-topics
  • improving the man page (which should mostly be a stub pointing to help)

2019 Notes Below

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.
• Bash has lots of documentation (not all official); Bash Reference Manual, Bash guide for beginners, Advanced Bash-Scripting Guide, BashPitfalls, Bash Cheatsheet. - what should be done to incorporate those ideas?

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"?