Docs need comments, too
May 10, 2017
Just like source code, sometimes docs need comments, too.
Recently I was documenting an esoteric, complicated feature of the Chrome DevTools UI. The source of my knowledge was a reply on the DevTools mailing list from one of the DevTools engineers.
In the past I would have documented this feature without leaving a note by myself about where I got the info. But then, somebody would file a bug on that very section, claiming that it was incorrect. I would go back to review the source but not be able to find it. Very frustrating.
So now, whenever I document a tricky section based on hard-to-find knowledge, I just add a comment with a link back to the source.
If I worked on a big writer team with many hands touching the docs, this approach could also be useful for shared resources. For example, if there’s a diagram in the doc, I could include a comment with a link to the source file.