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 for the big picture stuff but it’s an awesome first checker.

Here’s how I use it in the TelemetryDeck docs with reviewdog:

@daniel Looking into it now. It's now quick to run this thing... :)

@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.

@tonester Docusaurus, so got that covered. Also, the Vale suggestion by @daniel is a great one.

Sign in to participate in the conversation

Everyone is welcome as long as you follow our code of conduct! Thank you. is maintained by Sujitech, LLC.