DEV Community

Discussion on: Writing proper documentation. Why is it so hard?

ferricoxide profile image
Thomas H Jones II

Documentation has to be reflex.

Me? I hate having to answer the same question twice. I generally try to document as I go. When I'm done with a project, I like to think that there's no excuse for asking me questions, least of all the same question more than once (if I reply "what was unclear about what I wrote" and the asker's response to that is "oh, I didn't read it," I usually tell them, "come back to me when you've read it and tell me where the documentation's deficient: I'll fix it".

Similarly, I'm typically matrixed across a minimum of two projects any given week. I may be "temporarily" pulled off one project for as little as a few hours to as much as a few months. If I don't document as I go, there's no chance in hell that I'm going to be able to come back from a multi-day/week/month break and pick up where I left off.

In short, I write for me. And, if you want others to write, you need to figure out how to make them see that documenting's an effort that benefits them.