How do you write technical documentation such as requirements, goals, software architecture, and general project documentation?

Back in the pre-AI era, it was common to write long, multi-page documents that explained everything in detail. That approach had its pros and cons. The documentation was usually well organized and comprehensive, but it was also often boring to read and sometimes overwhelming.

What does it look like now, in the era of AI coding assistants? My impression is that large, comprehensive documents are becoming much less common and mostly remain in legacy projects or a few specific use cases.

It feels like the entire world has shifted to Markdown, so I assume technical writing is evolving in the same direction. It makes sense to break up those oversized documents into smaller, focused files so that both humans and AI agents can navigate and consume them more easily. That’s what I do for my side projects, and it has worked well so far.

On the other hand, at work we still tend to rely on large documents written by technical writers. The argument is that we’ve already established a structure around them, and that’s how our development process is designed.

What’s your approach to documentation for both personal and professional projects?

1. Pull up documented conversation - receipts ready
2. Search frantically for proof (sometimes find it)
3. Apologize even when I'm pretty sure we did discuss it
4. Avoid conflict - just do what they want now

We'll finish a feature, everyone's happy with it, and then it sits there. Review takes forever, then testing takes forever, then deployment takes forever. I feel like I spend more time shepherding code through the pipeline than writing it. Tried streamlining things a few times but the handoffs between teams kill any momentum. Any solutions for this?

As a hobby coder I generally use jupyter notebook. I haven't used VS in almost a decade. Jumping into C# for a Unity project, holy hell intellisense has become an adhd nightmare. How can I tone it down so I can still get useful info but not have to do keyboard gymnastics to type simple lines of code? For example whenever I type g, it autocompletes to global... every little thing I type I get pop ups asking if I mean this or that interrupting my flow, I just want to code! EDIT: SOLVED!

As a new lead I got into this situation that might be familiar to a lot of people.

The code base is full of tech debt (what else) that no one ever cleaned up because shipping features was more important. So important that the code base became a collection of poorly designed things over the years that barely anyone knows about or touches.

Things that should have been cleaned up years ago are now starting to become apparent. They drag us down.

With a new PM, the team somewhat is more organized now but reducing tech debt is not on anyone's radar. In fact, PRs are sometimes piling up debt again that could be avoided in the first place if people would stop rushing.

I want to get this under control. How do you manage this with a team?

I thought about suggesting to actively plan the reduction of tech debt and reserve 30% of every iteration for unplanned stuff (bugs, urgent requests) and tech debt reduction.

This is not very popular with business and PMs but what can you do? What is your way that got acceptance from both devs and the business?

Edit: maybe I want to add: with gracefully I mean actively planned and with wits. Fixing a bug because you passively run over it by accident is not what mean by that ;)