Hi kids!
let’s talk about ….. documenting how to run a project!! I know, I know. It’s the WORST!! However, every single developer coming behind you to maintain things will appreciate you! Don’t lock up the code so it’s impossible for others to test without some serious deep diving into the code. It’s just rude. You know how to run it and sharing knowledge is a good thing! This industry does not appreciate those who hoard information… that’s why we have blogs and sites like Stackoverflow
Some basic “please do this” steps:
If the solution needs a specific project or projects to run at start, note that
If there are multiple environment, document how to run locally in each environment. If you need specific config values, note them
If user secrets are needed, note that
If you need special permissions to handle security requests, note it
If the solution can be connected to using integrations, note it
If a file structure needs created on a local C drive, note it or check for the folder in the code. If it doesn’t exist, create it for them!
Of your company doesn’t have a documentation “space”, add all documentation to the Readme file
If the code has standards, note the standards
If there are values stored in a deployment tool instead of the code, give instruction on how to use it and how to add additional values
If your solution is in a collection of solutions, note those other solutions and if they all need to run at the same time
If unit tests need specific data, note it
If your database connections are stored elsewhere, make sure connections needed for local testing is noted
Note the company URL for all environments - dev, test, UAT, Prod
Lastly - don't overdo it. Only document when needed, like the code doesn't tell you already .... DRY (Don't Repeat Yourself)
These are the minimums for every single solution. You can absolutely add more if it’s needed, include screenshots, be specific. In this case, it is always better to have more information than less especially if you decide to leave the company. It is unprofessional to write untestable code and then dump it on someone who has to take days, weeks to untangle and figure out how to locally run and test something that simple instructions will negate.
Be a team player!
Love you, Liv 💜
Comments