When someone new works on your repository, make sure it is easy to get setup.
Imagine if we didn't have any documentation; if we all adopted the mindset of "I already know this, let others figure it out on their own."
No more books. No more Wikipedia. No more READMEs. No more StackOverflow. No more API references and tutorials.
Don't take what you know for granted. Someone else may not know what you know.— Clarice Bouwer (@cbillowes) September 22, 2016
Documentation is a very broad term and has a bad stigma to it. As it can apply to anything from the enterprise to the application—what is written today can be stale or incorrect tomorrow.
The code repository is something you have control over. It contains the application which translates the business needs to code.
Your repository is meaningless if someone else needs to work on it and can't even get setup. Use your README to help other software developers and assume they know nothing about the project. Here's what I think could help contribute to a great README file:
Is there a simplified architectural diagram that can quickly highlight the overall architecture at a glimpse? This changes over time so extensive documentation is probably not an option unless it can be automated or there is a role where someone needs to keep it updated.
Your project is probably referencing some dependencies. In .NET all Nuget packages and their dependencies sit in the root of the same folder. This makes it difficult to differentiate what was explicitly referenced and why.
If future developers are unfamiliar with the packages, the chances of cleaning unnecessary packages up later is slim to none.
List the dependencies that you have explicitly referenced and mention why.
If you have a standard for commit messages then state how commits should be written for new features, bug fixes, improvements and refactoring in this repository.
What other information needs to be present in the message; a link to the ticket number or the reasoning behind a change?
All the knowledge you accumulate during your journey with this repository is lost (only available in your mind) when you leave. What other knowledge can you share to help future developers on the project to avoid the same mistakes being made in the future.
The next time you think that documenting something will take too much time, think how you would feel if you were in the next person's shoes. Too scared to make changes, anxious about deploying and downright frightened to even look at the code.
Make the world a better place. Contribute to the README and write about what you learn so that others can benefit and start innovating instead of struggling too much.
Note: This may appear verbose but could be broken down into separate pages or linked out to other references. It doesn't have to be extensive but it must be good enough to get someone up and running especially if the person is new to the company or your team.
If your documentation does become extensive it could highlight problems within your solution that could be reflected on for improvements.