Today’s challenge. Write documentation guidelines without being too prescriptive while still getting team members to fall in line and apply said guidelines. 😅 (Tips are welcome.)
@appforce1 check out vale. It’s like a Linter for documentation, allowing you to automatically check for spelling, phrasing, structure, etc. Of course you still need a human https://github.com/TelemetryDeck/docs/blob/main/.vale.ini for the big picture stuff but it’s an awesome first checker.
Here’s how I use it in the TelemetryDeck docs with reviewdog:
@appforce1 keep documentation close to the code eg in repo as markdown or in the repo wiki. Don’t ask for too much detail. Ask them to put themselves in the shoes of how they were when they first joined the project - what would they want to know.
Everyone is welcome as long as you follow our code of conduct! Thank you. Mastodon.cloud is maintained by Sujitech, LLC.