[sheveksmath]

This past week I set up our project's Azure DevOps wiki, uses markdown and allows you to generate graphs using mermaid.js - very nice, especially since it's harder to blackboard ideas remotely. Although we were initially just using a README file, it's faster to contribute to the wiki and is easier to manage more information with it.

But regardless of whether you have a fancy doc site or just a single README, I think it's important to just get information down that's actually important and written as clearly as possible, and then sorting by how commonly that information may be needed. It's also helpful to put yourself in the shoes of a junior developer or someone completely new to the project: does x make sense outside of this context? Oftentimes when we refer to some project-specific concept, we don't realize that there are implicit mental dependencies that someone must have before they can understand what we're talking about. The best documentation makes the fewest assumptions they can get away with about the reader's previous knowledge.