That very much depends on what you mean by the old way. When I first started the old way Documenting meant you write very complex design documents up front, which inevitably in the first hour we discovered something very critical and important that was not in it and within a couple days the documents were completely unrelated to the reality of what we were implementing. By the end of the week, there was a large first of the document that still had to be implemented, but the document was so divorced from the reality of what the code was that it was useless to refer to.
However, instead you're referring to documenting as a few smart people stand in front of a whiteboard for a couple hours and sketch out the details. That is a valuable activity. Just remember that within a couple days you need to erase that whiteboard because it's useless anyway. These days I would use an LLM to help me create that, especially if it's a part i work on alone. However, it's only a help and I understand again that this is a guide to get me started but it won't match reality and so I'm not going to share it with others.
Thank you for your response. What you've said makes sense to me, and somewhat reflects my own experience.
To give some context, I've been working remotely since the start of my career and transitioned to a more content-oriented role last year, so I never progressed beyond being a junior engineer. But I do remember the deep discussions and technical planning sessions being the most rewarding and mentally challenging.
I have seen that AI has the same tendency of over-engineering solutions when you are in the documentation phase, where it tries to scope out the entire plan before I have a clear idea of what I wish to do. So I typically begin with a simple markdown doc and disable auto-complete before reaching out for it later.
There is value in detailed design documents. However it is questionable if the value is high enough as to be worth the effort even in the best cases. In the majority case only a small handful of people will ever care and they are people who will soon be maintaining the code - the detailed design makes understanding easier, but not by near as much as the effort required for the document.
If the document it to be useful it needs to be kept up to date. You can never go more than a couple hours of coding without updating the document. Every change will take half again longer than before because the documentation is part of the change. Everybody who reviews the code needs to also review the documentation change. Every other developer must read (not to be confused with review) the change as well so they know.
That's true ;)
Yes, I've started building a side project after quite some time now, and decided to intentionally be "dumb" about it. Feels quite rewarding and I'll definitely blog about it once it is in usable form.
That very much depends on what you mean by the old way. When I first started the old way Documenting meant you write very complex design documents up front, which inevitably in the first hour we discovered something very critical and important that was not in it and within a couple days the documents were completely unrelated to the reality of what we were implementing. By the end of the week, there was a large first of the document that still had to be implemented, but the document was so divorced from the reality of what the code was that it was useless to refer to.
However, instead you're referring to documenting as a few smart people stand in front of a whiteboard for a couple hours and sketch out the details. That is a valuable activity. Just remember that within a couple days you need to erase that whiteboard because it's useless anyway. These days I would use an LLM to help me create that, especially if it's a part i work on alone. However, it's only a help and I understand again that this is a guide to get me started but it won't match reality and so I'm not going to share it with others.
Thank you for your response. What you've said makes sense to me, and somewhat reflects my own experience.
To give some context, I've been working remotely since the start of my career and transitioned to a more content-oriented role last year, so I never progressed beyond being a junior engineer. But I do remember the deep discussions and technical planning sessions being the most rewarding and mentally challenging.
I have seen that AI has the same tendency of over-engineering solutions when you are in the documentation phase, where it tries to scope out the entire plan before I have a clear idea of what I wish to do. So I typically begin with a simple markdown doc and disable auto-complete before reaching out for it later.
There is value in detailed design documents. However it is questionable if the value is high enough as to be worth the effort even in the best cases. In the majority case only a small handful of people will ever care and they are people who will soon be maintaining the code - the detailed design makes understanding easier, but not by near as much as the effort required for the document.
If the document it to be useful it needs to be kept up to date. You can never go more than a couple hours of coding without updating the document. Every change will take half again longer than before because the documentation is part of the change. Everybody who reviews the code needs to also review the documentation change. Every other developer must read (not to be confused with review) the change as well so they know.
It is still worth doing if readers can run the project and see your reasoning. Write up one bug you traced and how you checked the fix.
Sure you can. AI needs inspiration to steal from and the material is getting very stale. Please make your reasoning as public as possible.
That's true ;) Yes, I've started building a side project after quite some time now, and decided to intentionally be "dumb" about it. Feels quite rewarding and I'll definitely blog about it once it is in usable form.