[skrebbel]

I’ve found that internal documentation is a great place to put timestamps. People often complain that eg architecture pictures or design documents tend to go out of date, as if that’s somehow a big enough problem to not make them.

Instead, consider making whatever documentation seems useful at a given moment and timestamp it with a clear, prominent “this was accurate on yyyy-mm-dd”. It will still be useful a year later, because people are actually very good at dealing with “ok this detail might have changed since then so I’m not going to let that confuse me when mapping the doc/diagram to the code” kind of stuff.

When things have diverged too much, just make a new one. And timestamp it!

[skrebbel]

Addendum: don’t rely on your git/wiki/document-system for tracking the timestamp. “This was accurate on $DATE” has a very different meaning than “this document was last edited on $DATE”. It might be 2 years out of date but someone fixed a typo last week.

Just put a sentence/textbox somewhere with the date. If someone does a proper update, they will proudly edit that sentence too.

[LelouBil]

French government websites do this for help articles, they have a "last edited" and a "last verified" date on each article

[skrebbel]

Love it!

[kiliancs]

I've found that keeping a changelog as part of my design docs and similar is a good way to keep engineers, even across teams, confident that what they are looking at is up to date and a good reference, and the right document to update if necessary.

[dspillett]

> It might be 2 years out of date but someone fixed a typo last week

Or it might have had a fuller update last week, but from older information (perhaps going from years old to months old) because it is information that has a high processing latency (like census data). Though in this case the date probably belongs in the text with the timestamp representing the edit date, either way both times should be made clear.

[alanbernstein]

And sometimes there is a "let's switch source control systems", which results in a wall of inaccessibility in the history.

[Cthulhu_]

Documentation maintenance seems underrated. For most of my career, information was dumped in a wiki, so that everyone could maintain it. But if everyone maintains it, nobody does.

Every project needs someone responsible for someone taking ownership of the documentation, including research and timestamping and the like. Have a todo list where the oldest document goes on top, check it for relevance and accuracy, cull it if it's outdated, get it up to date otherwise, and (as this comment recommends) update the timestamp.

My current project has a wiki going back years, loads of duplicate information, no clues whatsoever if it's still relevant.

[_glass]

Documentation has to be part of the process. Work according to the process. Do documentation reviews.

[dugmartin]

If you use VS Code there are a couple of extensions that insert the current timestamp with a hotkey. That makes it very easy to add to documentation.

I use this one that allows you to configure the output format:

https://marketplace.visualstudio.com/items?itemName=gieson.w...

[Archelaos]

I can only endorse this, but would like to add that I always put my name and email address and a version number on top of the document. The additional version number is useful for keeping track of changes. Often I indicate what changed since the last version of the documentation or I have a separate HISTORY.txt file in the documentation folder including all versions, dates an a brief comment, what has changed.

If a question comes up later, I can first ask the questioner which date or version of the documentation they are relying on. More than once, the problem has been solved simply by sending the person the current documentation again.