Investigate linter and resolve outstanding notices

[hayleycd]

Currently the linter runs and passes, but gives notices about areas in the documentation that aren't as clean as they should be, but doesn't actually fail.

• investigate whether this is the behavior we actually want
• if not, set up linter to fail on these issues
• fix outstanding "notices"