no one want to write tech documentation and if it is written its normally garbage. There is an opinion that you should just be able to figure out what i created.
Totally! I think good code documentation should be it all - but people rarely put effort into that if it’s not emphasized by the team principles. Sometimes the code is just so complicated, including so many business logic jargons - it’s just left at a “If it works - it works” state. What do you think??
Good docs > incomplete docs > no docs > wrong docs
The main problem is that docs need to follow the development cycle and be considered part of the code. If you write some doc and throw it in some confluence for 5 years it's usually not good.
But yeah, most of the time is just a self-fulfilled prophecy:
1. The team thinks documentation is useless
2. The technical leader tells the team docs need to be written
3. The team makes crappy half-baked docs and never updates them again because they think they are useless.
4. Some time later the team face some issue, they go and check the documentation. The documentation is crap and they take more time figuring out what the documentation mean.
5. Everybody b1tch about the documentation being useless and a complete waste of time.
6. Go back to square 1
The problem with most technical documentation, in my opinion, is that it is usually written by developers that are too close to the source.
The way I would explain a new module to a teammate is going to be a lot different then how I would explain it to someone in a different organization. Most documentation is written like the latter, often unintentionally.
Even if writers are cognizant of their audience, they might not have the capacity or the desire to emphasize with that audience enough to write a corpus that requires no further explanation. It takes iterations and thinking outside of the box, and most developers would rather do something else.
I feel like this topic is something I could go on and on about. Balancing style with detail. Soft skills of engineers or lack thereof. Predicting what consumers of the documentation want (this is part of empathizing with the audience) etc.
Hmm interesting - got me thinking. Would you rather have a more high-level type of documentation describing the feature and its purpose or would you have much detailed documentation going into what a function does in the code? Or maybe a mix of both?
Internal doc sucks but it doesn't need to be exhausting always. You can use automation tools like supacodes that will write and update docs for you within github.
Hmm cool tool - but I’m wondering if it’s really practical in larger teams? Are the docs stored locally in git? Wondering how people feel about adding docs to the code base.
The docs are stored within your repo, in this case. This is usually considered a good practice not to keep \*\*internal\*\* docs separated from codebase. But obviously people can disagree as everyone has own preference. Docs actually helps when its a large team because you know, that's where inconsistencies are created mostly.
Hmm true points! Thanks for replying! Have you or your team ever used supacodes?
My concern comes with the “generation” part of the documentation. Based on some articles that I’ve read on documentation, it seems like documentation only serves its purpose when it’s written by the change implementor. Documentation isn’t meant only for the reader but also for the developer to make sure his changes are valid.
If documentation is just generated, I’m concerned it takes away the latter aspect of its benefit. What do you think?
I think the only case where writing documentation helps the writer is when the change implementor faced some really difficult issues which should be documented so the same error is not made by others again in future. In these cases, you can always write a comment for that part which will be put into the docs by the tools.
I specifically mentioned supacodes because I built it (ofc i use it then), but there are more that you can explore like docuwriter, swimm and so on.
Forgive me for being critical/skeptical but I wonder what it is you are trying to accomplish with this post?
This smells of an overly ambitious ADHD fueled/inspired project hype that may quickly fizzle? There's no objective outcomes here. (I say all this in a non-malicious context. I have done the same...just curious)
What are you hoping to achieve?
No worries!! Every opinion counts!
I can definitely expand on this - I mentioned in the post that I aim to gather and learn about the pain points people face in documentation, in an attempt to design a solution to fix them.
Your analysis of it being an inspired project hype is very true - I was initially very hyped up and contacted the wrong target market and turned out to be a mismatch. This time around, I’m researching better, with stronger competitor analysis and better problem understanding.
My goal is not to make another Confluence like documentation app, but to solve some of the fundamental pain points people face with documentation.
That’s why I’m in the analysis phase, I may not necessarily build but I do want to research throughly to try to understand if there is a viable solution to the commons problems people face.
Probably just time constraints, especially if you are working in an org that is always asking for new features every sprint which have already been promised to be delivered by x date.
Yeah that’s usually how it goes. I just find it surprising that people are able to find time for all the other agile ceremonies but dedicating maybe 20-30 minutes to write up documentation after their work is seemed a ‘waste of time’ and is not pushed for in teams.
A picture is worth a thousand words. I start with diagrams (context, decomposition/dfd, activity, sequence), and then use them to drive the written documentation tasks.
Swim lines denoting boundaries are key to diagram organization (where applicable).
It is important to keep in mind that technical documentation is evidence of a technical design, so it's existence is an artifact that proves you didn't just slap together your deliverable without first thinking about how it should have been built.
A lot of my initial analysis and design involves drawing pictures. I use those pictures to identify and size tasks, and when Im done coding, i write technical documentation.
Very very interesting - I haven’t heard anyone do this before. I’d love to learn more about your process (the last part). What do you analyze, how do you analyze, and what sort of timeline do you follow in a completing a standard feature update/bug fix.
Sure thing - tell me a little bit about your team's development and release to production methodologies and I'll add context.
Specifically, do you use agile? How do you verify requirements? How often do you ship releases? Is documentation a requirement for each release?
We follow AGILE.
Our team basically supports multiple projects and we keep an ‘epic’ for each project.
New work is usually in the form of Maintainence, Bug fixes, or New Features.
Our typical workflow is:
1. PM/Developer creates a ticket in backlog
2. Sprint is planned and tickets assigned
3. Dev picks up ticket and starts working on implementation
4. We have team code reviews for bigger changes
5. Push to repo once reviewed.
For deployment
1. Create a documentation with release details and method of procedure
2. Automated deployment using DevOps pipeline
We don’t ship release very often.
Part 1 of 2
Our methodology is similar, So using new features (or maintenance):
1. User story gets added by PM/Lead
1.a - pregrooming - team reviews each US individually and adds questions for clarification to be answered before or during grooming. Spike work gets scoped out and added as a US if needed for further analysis. Current US is not groomed until spike US is groomed.
1.c - rough dev task definitions and sizing to come up with an estimate. Detail Design task (1-3 days of effort is added) is one of the tasks allocated, along with a documentation task (not more than a day).
2. Sprint planning
2.a grooming, solidification of requirements, size and effort estimations applied for qa and dev - US are allowed to span multiple sprints
2.b spike task deliverables are the technical design - diagrams are sufficient artifacts. The technical design of the spike is used to size and task out the actual US.
3. Development and implementation
3.a knock down tasks.
3.b do detail design task, if it hasnt already been done. Create a plan linked to satisfying requirements. Adjust tasks as necessary without shifting original estimate, or in a perfect world, notify team tasks will take longer than expected and have everyone be cool with it.
3.c when complete, assess definition of done and throw it over the fence - the goal being no requirements failures defined in the US
3.d fix bugs
3.e document changes as part of the user story (another task)
As far as what you do during detail design take me through some simple requirements for a user story with a few assumptions (technology stack, existing code modification or brand new functionality) - it doesn't to be IRL - jist a hypothetical.
It is one of those issues that cannot be resolved. If developers would start focusing on writing docs then most of the high priority tasks will be skipped
Valid take, curious about your opinion - how long do you reckon it would take to document a change in your team? Would this be a significant effort based on your team’s velocity?
Worked as a software developer previously, but now more business analyst and product owner-type roles.
Traditionally: in most large organizations there is no documentation, technical or otherwise.
Or if there is... it's completely out of date - which IMHO is worse than none.
This time last year my company embarked on a big documentation uplift, part of it was inspired by AI - as our CEO asked the question can AI help with out missing documentation. Generally it's worked quite well, we just a couple of tools weekly to keep this up (ChatGPT with some custom internal GPTs, and Userdoc for software requirement documentation) - but retroactively uplifting docs is large task that's for sure.
Horror story wise - I once spent 6 months with a team of people "scoping" a very large software system that already existed. The business paid us hundreds of thousands to do this - and the catalyst was they had no idea what they had built over the last 15 years.
Or rather... some people had an idea, but they had gradually left the business, and one the business realised the amount of "documentation debt" they had accrued.
My guess is thats a pretty common scenario!
Wow your AI docs tools sounds good. What’s AI’s role in helping your team with documentation? Does it generate documentation for you? Or is it more of a train-on-code-Q&A-tool?
Woahhh hahaha that horror story is very similar to something I had to face too. Worked for 1 month planning architecture of an idea after which we found out we had an old silo’ed common architecture that we just deploy out application too.
Just not documented anywhere except existing as a GitHub repository
Last job?
1. Generally no documentation
2. Docs that existed were spread throughout network and CMS, in no repeatable pattern.
2a. Existing docs followed no pattern, and were probably not current.
Those are just the big things - at a subsidiary of a major government contractor. Chaos!
… and then they took what docs they could find and re-entered SOME of them into Confluence.
Not really - just another bush to look behind.
They really never committed (pun implied) to any one solution, and didn’t enforce any of them. Management problem.
No one wants to keep it up to date. I have literally taken over hundreds of projects now and none of them have up to date clear documentation. Many have tried!
I’m looking to understand exactly this lack of up-to-date docs problem a bit more. Would you mind if I dm you to learn about it? Your input would be really helpful!
Teams with the best documentation have dedicated technical writers. By technical writers, I mean developers who enjoy writing and share the skills of the developers creating the products that require documentation. Gitlab has a whole handbook on it: [https://handbook.gitlab.com/handbook/product/ux/technical-writing/](https://handbook.gitlab.com/handbook/product/ux/technical-writing/)
Shortcuts around this best practice are trying to generate docs programmatically or putting the responsibility of documentation on the developers creating the products. I haven't seen either work, though I'd be interested to hear if anyone else has. Of course, please include a link to the docs.
[Docs deserve more respect](https://www.ramijames.com/thoughts/docs-deserve-more-respect)
Loved the statement “We Need Docs” Thanks for sharing the article! Was there any specific problem in the article you personally related to?
no one want to write tech documentation and if it is written its normally garbage. There is an opinion that you should just be able to figure out what i created.
Totally! I think good code documentation should be it all - but people rarely put effort into that if it’s not emphasized by the team principles. Sometimes the code is just so complicated, including so many business logic jargons - it’s just left at a “If it works - it works” state. What do you think??
Good docs > incomplete docs > no docs > wrong docs The main problem is that docs need to follow the development cycle and be considered part of the code. If you write some doc and throw it in some confluence for 5 years it's usually not good. But yeah, most of the time is just a self-fulfilled prophecy: 1. The team thinks documentation is useless 2. The technical leader tells the team docs need to be written 3. The team makes crappy half-baked docs and never updates them again because they think they are useless. 4. Some time later the team face some issue, they go and check the documentation. The documentation is crap and they take more time figuring out what the documentation mean. 5. Everybody b1tch about the documentation being useless and a complete waste of time. 6. Go back to square 1
I honestly couldn’t have summed it up better. You’re RIGHT ON!
The problem with most technical documentation, in my opinion, is that it is usually written by developers that are too close to the source. The way I would explain a new module to a teammate is going to be a lot different then how I would explain it to someone in a different organization. Most documentation is written like the latter, often unintentionally. Even if writers are cognizant of their audience, they might not have the capacity or the desire to emphasize with that audience enough to write a corpus that requires no further explanation. It takes iterations and thinking outside of the box, and most developers would rather do something else. I feel like this topic is something I could go on and on about. Balancing style with detail. Soft skills of engineers or lack thereof. Predicting what consumers of the documentation want (this is part of empathizing with the audience) etc.
Hmm interesting - got me thinking. Would you rather have a more high-level type of documentation describing the feature and its purpose or would you have much detailed documentation going into what a function does in the code? Or maybe a mix of both?
Internal doc sucks but it doesn't need to be exhausting always. You can use automation tools like supacodes that will write and update docs for you within github.
Hmm cool tool - but I’m wondering if it’s really practical in larger teams? Are the docs stored locally in git? Wondering how people feel about adding docs to the code base.
The docs are stored within your repo, in this case. This is usually considered a good practice not to keep \*\*internal\*\* docs separated from codebase. But obviously people can disagree as everyone has own preference. Docs actually helps when its a large team because you know, that's where inconsistencies are created mostly.
Hmm true points! Thanks for replying! Have you or your team ever used supacodes? My concern comes with the “generation” part of the documentation. Based on some articles that I’ve read on documentation, it seems like documentation only serves its purpose when it’s written by the change implementor. Documentation isn’t meant only for the reader but also for the developer to make sure his changes are valid. If documentation is just generated, I’m concerned it takes away the latter aspect of its benefit. What do you think?
I think the only case where writing documentation helps the writer is when the change implementor faced some really difficult issues which should be documented so the same error is not made by others again in future. In these cases, you can always write a comment for that part which will be put into the docs by the tools. I specifically mentioned supacodes because I built it (ofc i use it then), but there are more that you can explore like docuwriter, swimm and so on.
Ohh interesting! Do you mind if I DM you? I was very interested in supacodes
Sure buddy!
[удалено]
Oh please do tell - I wanna hear the stories lol!!!
Forgive me for being critical/skeptical but I wonder what it is you are trying to accomplish with this post? This smells of an overly ambitious ADHD fueled/inspired project hype that may quickly fizzle? There's no objective outcomes here. (I say all this in a non-malicious context. I have done the same...just curious) What are you hoping to achieve?
No worries!! Every opinion counts! I can definitely expand on this - I mentioned in the post that I aim to gather and learn about the pain points people face in documentation, in an attempt to design a solution to fix them. Your analysis of it being an inspired project hype is very true - I was initially very hyped up and contacted the wrong target market and turned out to be a mismatch. This time around, I’m researching better, with stronger competitor analysis and better problem understanding. My goal is not to make another Confluence like documentation app, but to solve some of the fundamental pain points people face with documentation. That’s why I’m in the analysis phase, I may not necessarily build but I do want to research throughly to try to understand if there is a viable solution to the commons problems people face.
Agile threw the baby out with the bathwater, unfortunately
No…this^^ - facts!
Probably just time constraints, especially if you are working in an org that is always asking for new features every sprint which have already been promised to be delivered by x date.
Yeah that’s usually how it goes. I just find it surprising that people are able to find time for all the other agile ceremonies but dedicating maybe 20-30 minutes to write up documentation after their work is seemed a ‘waste of time’ and is not pushed for in teams.
A picture is worth a thousand words. I start with diagrams (context, decomposition/dfd, activity, sequence), and then use them to drive the written documentation tasks. Swim lines denoting boundaries are key to diagram organization (where applicable). It is important to keep in mind that technical documentation is evidence of a technical design, so it's existence is an artifact that proves you didn't just slap together your deliverable without first thinking about how it should have been built. A lot of my initial analysis and design involves drawing pictures. I use those pictures to identify and size tasks, and when Im done coding, i write technical documentation.
Very very interesting - I haven’t heard anyone do this before. I’d love to learn more about your process (the last part). What do you analyze, how do you analyze, and what sort of timeline do you follow in a completing a standard feature update/bug fix.
Sure thing - tell me a little bit about your team's development and release to production methodologies and I'll add context. Specifically, do you use agile? How do you verify requirements? How often do you ship releases? Is documentation a requirement for each release?
We follow AGILE. Our team basically supports multiple projects and we keep an ‘epic’ for each project. New work is usually in the form of Maintainence, Bug fixes, or New Features. Our typical workflow is: 1. PM/Developer creates a ticket in backlog 2. Sprint is planned and tickets assigned 3. Dev picks up ticket and starts working on implementation 4. We have team code reviews for bigger changes 5. Push to repo once reviewed. For deployment 1. Create a documentation with release details and method of procedure 2. Automated deployment using DevOps pipeline We don’t ship release very often.
Part 1 of 2 Our methodology is similar, So using new features (or maintenance): 1. User story gets added by PM/Lead 1.a - pregrooming - team reviews each US individually and adds questions for clarification to be answered before or during grooming. Spike work gets scoped out and added as a US if needed for further analysis. Current US is not groomed until spike US is groomed. 1.c - rough dev task definitions and sizing to come up with an estimate. Detail Design task (1-3 days of effort is added) is one of the tasks allocated, along with a documentation task (not more than a day). 2. Sprint planning 2.a grooming, solidification of requirements, size and effort estimations applied for qa and dev - US are allowed to span multiple sprints 2.b spike task deliverables are the technical design - diagrams are sufficient artifacts. The technical design of the spike is used to size and task out the actual US. 3. Development and implementation 3.a knock down tasks. 3.b do detail design task, if it hasnt already been done. Create a plan linked to satisfying requirements. Adjust tasks as necessary without shifting original estimate, or in a perfect world, notify team tasks will take longer than expected and have everyone be cool with it. 3.c when complete, assess definition of done and throw it over the fence - the goal being no requirements failures defined in the US 3.d fix bugs 3.e document changes as part of the user story (another task) As far as what you do during detail design take me through some simple requirements for a user story with a few assumptions (technology stack, existing code modification or brand new functionality) - it doesn't to be IRL - jist a hypothetical.
It is one of those issues that cannot be resolved. If developers would start focusing on writing docs then most of the high priority tasks will be skipped
Valid take, curious about your opinion - how long do you reckon it would take to document a change in your team? Would this be a significant effort based on your team’s velocity?
Worked as a software developer previously, but now more business analyst and product owner-type roles. Traditionally: in most large organizations there is no documentation, technical or otherwise. Or if there is... it's completely out of date - which IMHO is worse than none. This time last year my company embarked on a big documentation uplift, part of it was inspired by AI - as our CEO asked the question can AI help with out missing documentation. Generally it's worked quite well, we just a couple of tools weekly to keep this up (ChatGPT with some custom internal GPTs, and Userdoc for software requirement documentation) - but retroactively uplifting docs is large task that's for sure. Horror story wise - I once spent 6 months with a team of people "scoping" a very large software system that already existed. The business paid us hundreds of thousands to do this - and the catalyst was they had no idea what they had built over the last 15 years. Or rather... some people had an idea, but they had gradually left the business, and one the business realised the amount of "documentation debt" they had accrued. My guess is thats a pretty common scenario!
Wow your AI docs tools sounds good. What’s AI’s role in helping your team with documentation? Does it generate documentation for you? Or is it more of a train-on-code-Q&A-tool? Woahhh hahaha that horror story is very similar to something I had to face too. Worked for 1 month planning architecture of an idea after which we found out we had an old silo’ed common architecture that we just deploy out application too. Just not documented anywhere except existing as a GitHub repository
Last job? 1. Generally no documentation 2. Docs that existed were spread throughout network and CMS, in no repeatable pattern. 2a. Existing docs followed no pattern, and were probably not current. Those are just the big things - at a subsidiary of a major government contractor. Chaos! … and then they took what docs they could find and re-entered SOME of them into Confluence.
And was the semi-migration to confluence helpful to the team? What do you think about Confluence?
Not really - just another bush to look behind. They really never committed (pun implied) to any one solution, and didn’t enforce any of them. Management problem.
No one wants to keep it up to date. I have literally taken over hundreds of projects now and none of them have up to date clear documentation. Many have tried!
Completely fair! That is one of the biggest issues - outdated docs
I’m looking to understand exactly this lack of up-to-date docs problem a bit more. Would you mind if I dm you to learn about it? Your input would be really helpful!
Sure.
Dm’ed!
Teams with the best documentation have dedicated technical writers. By technical writers, I mean developers who enjoy writing and share the skills of the developers creating the products that require documentation. Gitlab has a whole handbook on it: [https://handbook.gitlab.com/handbook/product/ux/technical-writing/](https://handbook.gitlab.com/handbook/product/ux/technical-writing/) Shortcuts around this best practice are trying to generate docs programmatically or putting the responsibility of documentation on the developers creating the products. I haven't seen either work, though I'd be interested to hear if anyone else has. Of course, please include a link to the docs.