4 ms·
Writing for "you, but three years ago" is excellent advice.
by simonw 5mo ago
Writing for "you, but three years ago" is excellent advice.
- ryanisnan 5mo agoTotally! I like the bit about writing for a colleague, because this gives you a much more relatable concept I think.
- dredmorbius 5mo ago"You, before you embarked on this project" is another good target. Much of the technical documentation I've written was effectively how I got from prior-to-current-project-me to after-current-project me. And is often written for future-me-who's-forgotten-what-I-learned-in-the-process. What TFA fails to address is the option of either specifically naming prequisite knowledge OR basic prerequisite references. The number of sysadmin / tech manuals which re-iterate, e.g., basic bash/shell/editor commands, networking concepts, etc., etc., rather than simply pointing at a good definitive guide is ... frankly embarrassing. I'd rather see one good continuously-updated reference than thousands of writers reimplementing poorly-written, outdated, and very one-sided references.
- Shellban 5mo agoOr "you, but three years from now" in some cases. Logging my random OS changes or what were at the time "one-time shell scripts" in my journal has proven invaluable in some cases.