Where Will the Docs Live? (2017-03-29)

We’ve been having a bit of disagreement about where docs live. Should we create enterprise-style software documentation, documenting how to install and run the software? Yes. I think so. Should we create user-level (though developer-directed) software documentation that gives example usage, API examples and the like? Sure. Good idea.

And where should that documentation live?

“Why, in (insert enterprise flavor wiki name here), of course!”

Let’s look at the downside of that response (though I suspect we’ll give in in the end):

  • Documentation, in general, is even more prone to bit rot than code
  • The likelihood of being stale is greatly enhanced by “distance”
  • Inline code comments often bear no resemblance to truth, and it’s RIGHT THERE!!
  • With an appropriate level of attention we can fix this. (And we’ll be the first.)

Let’s go in a different direction for a moment.

We’re leaving out an entire flavor of documentation, the kind of documentation written by developers for their colleagues – and, perhaps most significant, THEIR FUTURE SELVES – that describes really important things like:

  • what’s the underlying design of the solution?
  • what was the problem this code is trying to solve, anyway?
  • why the hell was it written this way? (And even, the ever rare “why we didn’t write it that way…”)

This “how and why” documentation is remarkably valuable in general and absolutely indispensable when it’s really needed. And it sure seems it ought to live with the code where it belongs. Markdown is perfect lightweight format for this kind of documentation. So create a MOTIVATIONS.md or a NOTES.md or a WHYIDIDITTHISWAY.md or a IFIHADTODOITALLOVERAGAIN.md. Recording your thoughts just might help someone who has to deal with your code in the future. Even if it’s you.



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s