Something this author touches on that I find people overlook a lot in documentation: There is a lot more to documentation for a repo that comments in files. There's so much information that is...
Something this author touches on that I find people overlook a lot in documentation: There is a lot more to documentation for a repo that comments in files. There's so much information that is critical to team success that doesn't belong in file comments. Every repo should have an extensive readme. I think I've talked about it here before, but I have been overhauling documentation at the company I just started working for. When I finish a repo, it will have a README that at minimum says:
(1) What the repo is called
(2) High level: what is the problem the repo is trying to solve, and very high level how does it do that. Example: "We needed a way for developers to automatically create email alerts or tickets when specific events happen. <Repo Name> takes an input in son via curl, converts it into a known format, queries a database to get contact information for the team, and generates an alert (email or ticket).
(3) Link to the confluence page for the repo (all our repos are supposed to have one)
(4) Requirements
(5) File structure: I go through and give a one sentence description of every item in the repo. Configuration files, docker files, folders, everything. Doesn't have to tell you exactly how it does what it does, but you should be able to use it to narrow down what file you need to look in to make a change. This one is probably overkill but it saves new devs hours and gives them a lot more autonomy.
(6) Workflow: How do you go from ticket => production. Should tell you order to do things and how to do them. I go overboard again. Example: check out repo, create a new branch, update version number, make changes, make unit and integration tests if possible, run tests (and tells you the commands for how to run the tests), fix as necessary, deploy to dev (and how to do so and how to debug if there are issues with kubernetes/docker for deploying), see if you broke something or if the change works, make an MR, wait to pass CI and get merged, push to prod (and how to do so and how to debug deploy issues), and how to get back to a safe state if something breaks.
(7) Tips for debugging
(8) How to add to the CI
(9) Any specific details that might be useful for that specific repo
(10) known bugs/technical debt
It means the difference between me having to hold the hand of a new dev and tell them what files to look in and what changes to make and how to do things + maybe they remember everything and maybe they don't, vs me sitting next to them while they look around with the repo and answer questions as they need help. Its a lot of work, but I'm building out general templates for a lot of our repos to lower the burden upfront.
Something this author touches on that I find people overlook a lot in documentation: There is a lot more to documentation for a repo that comments in files. There's so much information that is critical to team success that doesn't belong in file comments. Every repo should have an extensive readme. I think I've talked about it here before, but I have been overhauling documentation at the company I just started working for. When I finish a repo, it will have a README that at minimum says:
(1) What the repo is called
(2) High level: what is the problem the repo is trying to solve, and very high level how does it do that. Example: "We needed a way for developers to automatically create email alerts or tickets when specific events happen. <Repo Name> takes an input in son via curl, converts it into a known format, queries a database to get contact information for the team, and generates an alert (email or ticket).
(3) Link to the confluence page for the repo (all our repos are supposed to have one)
(4) Requirements
(5) File structure: I go through and give a one sentence description of every item in the repo. Configuration files, docker files, folders, everything. Doesn't have to tell you exactly how it does what it does, but you should be able to use it to narrow down what file you need to look in to make a change. This one is probably overkill but it saves new devs hours and gives them a lot more autonomy.
(6) Workflow: How do you go from ticket => production. Should tell you order to do things and how to do them. I go overboard again. Example: check out repo, create a new branch, update version number, make changes, make unit and integration tests if possible, run tests (and tells you the commands for how to run the tests), fix as necessary, deploy to dev (and how to do so and how to debug if there are issues with kubernetes/docker for deploying), see if you broke something or if the change works, make an MR, wait to pass CI and get merged, push to prod (and how to do so and how to debug deploy issues), and how to get back to a safe state if something breaks.
(7) Tips for debugging
(8) How to add to the CI
(9) Any specific details that might be useful for that specific repo
(10) known bugs/technical debt
It means the difference between me having to hold the hand of a new dev and tell them what files to look in and what changes to make and how to do things + maybe they remember everything and maybe they don't, vs me sitting next to them while they look around with the repo and answer questions as they need help. Its a lot of work, but I'm building out general templates for a lot of our repos to lower the burden upfront.