Depends on what you're doing... For a developer focused documentation, I often will write a bit of the documentation up front as a project is getting setup with the intent on how it should work locally (or per developer). Then fill in details as each part gets more flushed out. Same for library APIs, command-line scripts/tools etc.

For end-user products with a user interface, less so as it comes down to being flexible... similar with dashboards, as a developer I often don't know what is wanted up front... when something is asked for and you learn the domain more, it can come together easier. Larger projects with a front end component and many developers, nearly have to forget it at the dev level.

Writing docs, especially detailed and complete, can really save you in the long run. Plus the people that come after you will greatly appreciate your efforts.

> 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.

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.

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.