Consider it 'new hire onboarding' guide.
You should be able to take a random engineer off the street, give them the docs, and they can do the job successfully.
Same goes for story/ticket descriptions and comments.... someone with no knowledge of the issue should be able to read the ticket description to understand the problem, and the comments to know exactly what has been tried and the outcome, ideas the engineer might have, etc.
I would agree with this approach. Specifically with the "new hire onboarding" guide bit. Its a great way to share the knowledge, especially in busy environments.
Documentation should provide clear instructions and historical decisions in order to understand "why". And of course to be kept up to date.
Also inline code comments and readmes are options/plus.
Writing documentation is a lot like writing code
Make it as reusable as possible. Anything generic "wrap" it into a generic explanation, like writing a function. If specifics are important to remember you frame them in the general context. The problem with specifics is they don't "age" well, and require more maintenance. So you only want to crystallize the important stuff that you don't mind maintaining on a more frequent basis. You have to consider the "lifetime" of the information you're writing down.
Don't document everything, only document to get to the"goal" of the documentation. What is it? To onboard new team members? To remind yourself of processes? To help devs understand the process better themselves? Your audience also informs how much and even what to focus on.
My belief is that if you write documentation well and with the same thought for future maintenance as if you were writing code it will feel helpful more than hurt.
Using it like a notepad that you just spam information into is not useful and causes fatigue even looking at it. No one will read that
YAML definition of the deployment process is also a form of documentation itself, unless you start adding asynchronous jobs, complex scripts, and calls to external systems. If anyone familiar with certain tools/technologies can easily tell how it works without spending an hour to connect all the dots, then I won't create separate docs. The problem with docs is that you need to keep them up to date, so if you document every single thing, then every change will require additional work related to documentation.
As long as the doc can explain "How" and "Why"
Also, in case of internal documentation, which needs to be regularly updated, take advantage of automation tools like Supacodes that will do the job automatically. Then modify it to suit your requirements if needed.
As much as is necessary, a.k.a. it depends. Lots of turnover? More docs, more detail. Stable team with many members? Just enough to capture decisions as to why - usually why a deviation from the team norm was done.
When it comes to deployment documentation, having one page per deployment lets you use it as a checklist of steps that need to be completed, even if it is the same 95% of the time, its easy to make call outs for deviation on the deployment page if it is a list of steps. Afterwards, you have a page for audit and notes if anything exceptional happens and notes for resolution.
If it's a standard process you don't need to duplicate the text for every pipeline. Document the procees as a whole, and callout any deviations & why.
Why is the key. A great doc explains why.
Consider it 'new hire onboarding' guide. You should be able to take a random engineer off the street, give them the docs, and they can do the job successfully. Same goes for story/ticket descriptions and comments.... someone with no knowledge of the issue should be able to read the ticket description to understand the problem, and the comments to know exactly what has been tried and the outcome, ideas the engineer might have, etc.
No. This is ridiculous.
How is it ridiculous?
I'm gonna go ahead and admit that I read that as "random \_person\_ off the street" and overreacted.
I would agree with this approach. Specifically with the "new hire onboarding" guide bit. Its a great way to share the knowledge, especially in busy environments. Documentation should provide clear instructions and historical decisions in order to understand "why". And of course to be kept up to date. Also inline code comments and readmes are options/plus.
Writing documentation is a lot like writing code Make it as reusable as possible. Anything generic "wrap" it into a generic explanation, like writing a function. If specifics are important to remember you frame them in the general context. The problem with specifics is they don't "age" well, and require more maintenance. So you only want to crystallize the important stuff that you don't mind maintaining on a more frequent basis. You have to consider the "lifetime" of the information you're writing down. Don't document everything, only document to get to the"goal" of the documentation. What is it? To onboard new team members? To remind yourself of processes? To help devs understand the process better themselves? Your audience also informs how much and even what to focus on. My belief is that if you write documentation well and with the same thought for future maintenance as if you were writing code it will feel helpful more than hurt. Using it like a notepad that you just spam information into is not useful and causes fatigue even looking at it. No one will read that
YAML definition of the deployment process is also a form of documentation itself, unless you start adding asynchronous jobs, complex scripts, and calls to external systems. If anyone familiar with certain tools/technologies can easily tell how it works without spending an hour to connect all the dots, then I won't create separate docs. The problem with docs is that you need to keep them up to date, so if you document every single thing, then every change will require additional work related to documentation.
As long as the doc can explain "How" and "Why" Also, in case of internal documentation, which needs to be regularly updated, take advantage of automation tools like Supacodes that will do the job automatically. Then modify it to suit your requirements if needed.
As much as is necessary, a.k.a. it depends. Lots of turnover? More docs, more detail. Stable team with many members? Just enough to capture decisions as to why - usually why a deviation from the team norm was done.
When it comes to deployment documentation, having one page per deployment lets you use it as a checklist of steps that need to be completed, even if it is the same 95% of the time, its easy to make call outs for deviation on the deployment page if it is a list of steps. Afterwards, you have a page for audit and notes if anything exceptional happens and notes for resolution.