[gregkerzhner]

The problem with docs is that unlike code, documentation has no mechanism to keep it updated as things change. Even something really close to the code like code comments tend to get stale. Separate docs are hopeless - unless you are the owner of the code and the doc, and have great discipline, docs are almost guaranteed to diverge from the code.

When this happens, it’s tough to say what’s worse - a stale, and sometimes wrong document, or no document at all. So, in my career I’ve come to rely less and less on docs, and more and more on just reading the code. Docs can lie - code rarely does.

[ChrisMarshallNY]

I've found that headerdoc-style documentation works very well.

It does require a teensy bit of extra discipline and vigilance, on my part, but it is usually supported by many tools.

If I do it that way, it's automatically displayed in mouseovers in Xcode, and can be compiled into organized sites, by Jazzy.

I write about my methodology, here: https://littlegreenviper.com/miscellany/leaving-a-legacy/