- At the AGM we formed an ad-hoc documentation working group.
- One of our ideas was that we should have a last reviewed date for
documentation, so that we can periodically implement a review
mechanism (GitHub Actions posts to Slack for a regular documentation
outdatedness check?) to track how old docs are and ensure they're
still relevant.
- This is a first step towards that goal, by adding a `last_review_date`
to the metadata of all docs with a date of earlier than Homebrew's
inception because everything needs reviewing so that we start from a
good base!
v0.13 of the `markdownlint` gem just got released and it has
a few new rules which are docs ended up failing. This fixes
those linter errors so that CI is no longer red.
Rules:
MD055 - Tables: Each row must start and end with a '|'
MD057 - Tables: In the second row every column must have at least '---',
possibly surrounded with alignment ':' chars
Anywhere we can use `blob/master` we can use `blob/HEAD` instead. This
will make life easier if we ever rename our default branch in future
(once/if Git and GitHub provides the necessary tooling to do so).
It was not clear (to me, at least) that non-ruby external commands should not contain a file suffix. Homebrew will ignore a file `cmd/brew-extcmd.sh` instead of printing a warning or registering it as `brew extcmd.sh`
Bare URLs are auto-linked on GitHub but not on docs.brew.sh, so I added
angle brackets around them where appropriate. Also converted
Markdown-linked URLs for clarity.
GitHub now nicely generates a documentation site for us at
http://brew.sh/brew based on our docs folder. Optimise the output of
this and the GitHub docs directory for readability and the various user
groupings.
Patrick Linnane