[huganabaga]

> Writing documentation is always a time sink, though, in my experience. Or maybe I'm just not good at it :P It's usually an additional day of work overall, though.

And it saves you days and days of re-discovering truths about your code weeks/months/years down the line. Sometimes those rediscovered facts are not even true which will come bite you big time.

Integrate your documentation with your testing. That makes it easier to create and maintain. You don't have comprehensive automatic tests? Then that's your problem right there.

[t-writescode]

There are several forms of documentation:

  * comments in code
  * team-based comments
  * project design docs
  * knowledge-base articles for handling on-call rotation around feature
  * how-to guides for customers

Each of these has a different cost and a different direct/external usefulness. I absolutely believe in good documentation and I absolutely believe that it's valuable. It does not negate the extra cost of including these forms of documentation - especially the "not-in-code" documentation.

[huganabaga]

Of course they "cost". But the issue is the mindset that they are "extra". They are not. They are an integral part to professional software engineering. You can't take them away without moving from a professional craft into some hobby hack.

When developing medicine you wouldn't consider safety studies as "extra". When you fly an airplane then the take off checklist is not "extra". Arguing that automated test suites or documentation are just "extra" on top of making software and could be skipped is similar to arguing that you could fly a plane without any checklists or releasing medicine to the public without evaluating its safety. That's just unprofessional nonsense.