DEV Community

Discussion on: 💻 Documentation as code

Collapse
cubiclesocial profile image
cubiclesocial

Programmers hate writing documentation. Most programmers, anyway.

I don't. For me, it's probably the most enjoyable and exciting part of writing software because it usually represents the last step of a software release, which means something's about to head out the door. Also, while writing documentation, I usually am looking at the source code and typically spot at least one or two last-minute mistakes (bugs) that would have made it into the release.

Basically, if you aren't writing documentation for your software, you are missing out on supplying your customers with good documentation such that they will constantly bother you by opening tickets/issues (i.e. waste your time) AND your software will have more bugs in it. That's right, good documentation = fewer open issues on issue trackers. For me, most issues that get opened are actually documentation bugs, not software bugs (e.g. not enough code samples such that users try to use my software incorrectly and get lost/confused).

Collapse
adamcoster profile image
Adam Coster Author

I absolutely agree. Documentation is a lot like testing: at first it feels like it's in the way of "productivity", but once you've had a project in use for more than a few weeks you quickly learn how much time you lose later by not front-loading tests and docs.

I also used to write the docs last, but eventually I started writing the docs first, then the tests, and finally the code. That's helped a lot to prevent me from creating features I didn't actually need, and from having to redesign APIs after realizing I hadn't covered all use cases.