As a technologist, I thought I'd need to write things twice but it's actually three
Read this article in:
tl;dr: production code, test code, AND documentation.
Certified public accountants are used to writing things twice, in the double-entry accounting system. This helps to avoid some mistakes. Programmers in interpreted languages, such as myself, are used to test-driven development (TDD), where every piece of functionality is reasonably covered by a test. In a way that is a double-entry system. However, there is at least one piece missing.
I've found that if I don't document the functionality, it is as if it disappears, or was never there. So I made it a rule to write some documentation for every exposed bit - be it a piece of functionality, or an element of a UI. At the very least, I'm making a note of the work done in the changelog/worklog. And I'm making that public. Publish or perish, right, and if a functionality is implemented by never used, noone is better off for it.
Describing the user-facing UI in a README.txt file is actually good enough. I know because I go back to reading them all the time. Filling out the doc/ folder in the repo has also proved useful. If I don't remember how anything was done, maybe I can read it there. And if I wrote documentation that'll never be read - hey, that's okay too.
Too often documentation is missing or is sub-par. At the same time, too many online resources describe things that don't exist, or are garbage. Why don't we reconcile the two? Program useful tools, *and* write the documentation about how to use them.
Good software deserves good documentation. Great engineering isn't just about writing code. It's also about sharing their knowledge and making their expertise useful.
