3 ms·
At work, I've been writing a word document to explain every part of a program I've written and how each element interacts with the rest. It's been very helpful
by LeftHandPath 5y ago
At work, I've been writing a word document to explain every part of a program I've written and how each element interacts with the rest. It's been very helpful to find things that don't make as much sense as I thought they did when I wrote them, and revealing old code that is no longer used anywhere in the application. And I've caught a few places where outdated .txt / .md / inline-doxygen documentation lies, too.
Writing a summary document really forces you to get to the nitty gritty and catch things that a casual review would miss.
- chii 5y agoBut wouldn't this summary document be better as a form of comment in the source code rather than a separate document that will become out of date the next time someone else makes changes?
- KronisLV 5y agoFurthermore, wouldn't a Markdown document be a bit better as opposed to Word? That way, you or anyone else could easily search through its contents alongside the rest of the codebase, were it to be included in the repository, whereas that wouldn't work with Word, because it's a proprietary and binary format (unless you open that file in particular).