[hnarn]

Your comment makes me think that writing primary documentation should always be the job of developers, with time dedicated for the task, and technical writers can do the polishing and categorization that will likely be necessary for it to be published. Being the only one responsible for documentation while not being a developer must be a nightmare.

[blueboo]

I’ve noticed the master software engineers around me tend to have a particular acute sense for naming things, as if after living with and mastering the universe of abstractions around their craft they’ve embraced the linguistic dimension of the work, minimizing cognitive load and aligning execution with intent.

There’s no sense in work cultures I’ve experienceD that engineers should take in documenting their work individually, but having code do what it says on a deep level promotes, ah, grok-ability. But maybe leaving at that leads us inevitably to flawed self-documentation.

[ldng]

Naming tings is so important. Even more so if you know you will not have time the document properly. Typical sign that someone did not take the time to name : utils, shared or misc ...

Seen it so many time in poor quality project. Hardly ever in project that have a high quality bar set.

[CraigJPerry]

Yeah in practice there’s just no other way in the places I’ve worked. The problem I’ve encountered still though is getting developers to estimate sufficiently to give that time. Developers massively underestimate (myself included).

[Viliam1234]

If you have waterfall, there is usually not enough time to make the product itself, and documentation is much lower priority than that.

If you have agile, in theory all developers are replaceable. In reality, a few have writing skills, but most don't.

[lonelappde]

The problem is that you are estimating instead of producing and measuring. Just take the time and succeed or fail. Don't estimate it