Documentation is outdated and incomplete

[ericcornelissen]

First of all, I really like Capslock and what it does! However, I feel that it can be hard to use for outsiders (as evidenced by various issues: #1, #35 (comment), #53, #199, #266). I believe part of the problem is a lack of understanding (#199), a part is outdated documentation (#35 (comment)), and another part of it is missing documentation (#266). I think all of these can be addressed, but I'm particularly interested in the latter two gaps (as I personally don't have issues pertaining to the former).

For this reason I would propose (and be interested in contributing, if there's interest) two overarching categories of changes:

1. Simply updating the documentation .
   • The docs haven't been updated in two years all the while the following changes have been made (probably an incomplete list): 526f799, 2aae6b0, 4693513, 4be1944, 2a216f5, e505c8d, d8bfb16, 8312760, 39f66c6
   • capslock-git-diff was created but not included in the documentation.
2. Add examples/instructions for expected workflows, of which I think there are two:
   • Auditing: Use Capslock as an auditing tool to help review packages. This is more or less already covered by the existing documentation.
   • Integration: Integrate Capslock into a project to track capability changes and be notified of changes. This is, I believe, sorely lacking.

Moreover, some smaller problems I encountered while writing this up:

• There is no link to the documentation in the README (not counting the link specifically to the caveats).
• Code snippets in the docs don't have syntax highlighting.