alt Hacker NewsMy undergraduate research advisor told me "Papers and presentations are not murder mysteries." I try to keep that in mind whenever I approach explanatory writing, because the purpose is to help the audience reach understanding of where you ended up, not to replicate the epiphany you had yourself.
Replies
Heh. Mine, before the diploma defense, literally told me "Assume that the panel knows everything about the math except for the stuff your did in your thesis, so tell them about that. Don't bother explaining what 'error correction codes' are, tell them about your specific construction and practical boundaries you've determined". Which, I guess, is precisely "the reader knows everything I know except this one thing" antipattern but then again, blogging is different from e.g. conference presentation, isn't it?
I was handed the paper: A rational design process, how and why to fake it [0]. It's still one of my favorit papers. Basically it tells you to, when writing documentation, go back and put in later findings in the place it would been, if the world had been completely rational. Just leave out all the weaving and late discovery, very few people cares. Retrofit documentation to pretend that everything and everyone was completely rational and had all the knowledge at the correct times. It can cut down documents by a lot.
0) https://users.ece.utexas.edu/~perry/education/SE-Intro/fakei...
My PhD advisor said something similar, but he also said papers tell a story. There are a lot of stories that aren't murder mysteries nor suspense novels. Your paper shouldn't be a novel and especially not a suspense one