Refresh, Review, Recycle

Writing things down takes time and effort. Writing well takes a whole bunch of time and effort.

This doesn't mean that having more things written down is always better. As a developer, having out-of-date documentation or of questionable accuracy is a drag when trying to learn something or when trying to hunt down a specific detail.

That's why I appreciate having documentation that are both versioned and include a 'last updated' field that gets tracked for me. This supports a workflow where you regulary go back and see what documentation is old to bring it up to date (refresh), make changes to complete missing sections or adjust to current state (review), and remove old documentation (recycle - as in recycle bin).

It is nice to leave a marker when you delete something from your documentation system - whether for end users or internal designer, both cases are the same. I also do this with code and header files, leaving a comment saying something like A prior version of this file included an implementation of Foo. Keeping a couple of lines with the description and maybe code names will help people find this in the future, and then let them know where to go look in the file history.

I work day-to-day with wiki systems that provide good support for this - even MSDN / Microsoft docs are in on this - but SharePoint works just as well when you have a bunch of design documents or write-ups.

Enjoy your up-to-date and relevant documents!

Tags:  writing

Home