Hacker News Reader

Corollary: the documentation must be written to speak to the stupidest person in your team/company who you expect to use the product it describes. Otherwise, you may end up with a documented system that you can’t use or fix.

Fortunately, that’s often me (a supervisor), so I get to be self-deprecating when conveying this requirement.

View on HN

I also find that hypothetical "interns" are great for this. Something about "this person without a degree, who probably hasn't been working for very long, who doesn't know your organization or who to ask, and is probably very scared of looking or sounding stupid."

It doesn't necessarily imply or require stupidity, but in my experience on both sides of it (writing docs now, and having been that intern), they actually make pretty great litmus tests for documentation and how accessible organizational knowledge is.

When I write process/operating docs, I write it for the person who is on call, at 02:00 Sunday morning, after overindulging in alcohol Friday night. I don't assume stupid, just not firing on all cylinders due to being half awake and distracted.

Reply on news.ycombinator.com