There are many things to like about Github’s published document on how they should communicate. I like the idea of asynchronous communication as priority. I love that they want to write things down, and in an ideal world they want to maintain documentation as a first priority in a project. Really I have nothing to fault in the documentation.

Where I struggle with it is when I work with companies that say they value these types of ideas, but they almost always get pushed aside in the name of some feature that must ship. There are claims that the next development cycle will be different, but it’s not.

The only way to get maintenance done is to stop and do maintenance and stop pushing features. The only way to get documentation done is to stop and do documentation for every feature and not count the issue as done until the feature has documentation.

Another key part of their process is to assume that the people you’re communicating with don’t know what you’re talking about.

If you reference something – be it a prior issue, the pull request that implemented a feature, a line in a file, whatever  –  and that thing has a URL, it’s your obligation to find that URL and make that reference a link. Even if the reader could theoretically search for it, you are infinitely more familiar with the thing you’re referencing, and given a comment read by 5, 10, or 50 people, it’s more efficient for you to look it up once than for readers to look it up 50 times. Not to mention, on GitHub, linking to another issue or pull request creates a visible cross-reference, meaning that just by commenting, you create an organic map of the organization’s knowledge

This type of assumption happens to me all the time. I get issues submitted with acronyms I don’t understand, no screenshots, and no URL to the page. Thus I spend the first 30 minutes trying to figure out what we’re talking about and then rewriting the issue to be descriptive.