Code is the best documentation, it's what I seem to always end up consulting. And always in sync. Plus some guide to the overall architecture. Now... a pattern

Code is the best documentation, it's what I seem to always end up consulting. And always in sync. Plus some guide to the overall architecture. Now... a pattern language was meant to provide this, but failed. Perhaps, since a program is a theory, to understand the structure of the code, you must understand the structure of the problem/domain... and there's no shortcut. But even if so, a helpful guide seems possible. Autogenerated docs can help navigate the codebase, but tools can autonavigate just as well. They could show the overall code structure, but don't. They could be in sync, but aren't. A minimal but complete (all-steps) example, partly to learn from. and build on, and also to assure me that it works. Idea: I keep kinda expecting the text alongside each file/dir on github to be a comment on that file/dir (instead of its latest commit message). Could be incredibly valuable for navigating a codebase and grokking its architecture. (Though prone to desync.) I also like the format of a commit message for this: <50 char summary line, optional further lines. code: electronic documentation: edoc