-
-
Notifications
You must be signed in to change notification settings - Fork 150
Documentation Strategy
andychu edited this page Jul 24, 2020
·
8 revisions
Related: Oil Language Docs
- 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)
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?
- Human-written text - what formatting? - Markdown, rst, something else?
- builtin signatures from
osh/builtin.py
, etc. - ? ... Test cases ... ?
-
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)
- 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?
- 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.
- ... Have a single point of truth, but don't go overboard. i.e. I think the Python project believes in "separately-written docs"?