Documentation should always strive to be explicit and thorough, explaining the purpose of the file, class, function, etc. being documented well enough that somebody new to the file (or somebody reading this online without access to the source code) will have a good understanding of what’s going on and how things work.
Don’t go so far as to describe the inner workings of the actual code itself (that’s what code comments are for), but do give a higher-level overview of the code.
If you’re having trouble writing the docs, or you’re not sure your docs are coming across right, grab another person or even a rubber duck 🦆. Read your docs to them or explain the class/function out loud. That’ll help you solidify your thoughts, making it more likely that other people will understand your docs better.
We expect all documentation to be free of spelling errors, typos, major grammatical problems, and to have correct punctuation.
Try to make sure your "voice" matches the other docs in our codebase, too. This isn’t always easy, but give it a shot.
We will review and offer suggestions if we find anything we’d like changed.