?

Log in

No account? Create an account
What documentation is good for - Lindsey Kuper [entries|archive|friends|userinfo]
Lindsey Kuper

[ website | composition.al ]
[ userinfo | livejournal userinfo ]
[ archive | journal archive ]

What documentation is good for [Mar. 7th, 2010|08:40 pm]
Lindsey Kuper
[Tags|, ]

Epiphanies always seem blindingly obvious after you have them. Yesterday, one of last semester's C311 students wrote to me asking for help with this week's Compilers assignment. (This week, the assignment is harder than usual, and they've been told that they can get help from anyone they want, including former students of the course.)

It's been a year since I wrote my compiler. I don't remember any of the details. I didn't think I would be able to give any advice at all, and I almost wrote back saying as much. But I decided to take a quick look at what I had done this week a year ago, just in case it would jog my memory. When I did, I was amazed to discover that I had documented everything. There was something surreal about writing back to my student. Basically, by copying and pasting from my own comments and scratch paper, I was able to craft a message that seemed to make sense, even though I still didn't remember any of the details of what I was discussing. And my student just wrote back, telling me that it helped a lot. And then, today, I was able to help another former student in exactly the same way.

I feel like I just now found out what documentation is actually good for.

LinkReply

Comments:
[User Picture]From: perligata
2010-03-08 02:46 am (UTC)
I love that feeling. It's like, "Oh, former me, you were so wise! Thank you for not being lazy or arrogant!"
(Reply) (Thread)
[User Picture]From: lindseykuper
2010-03-08 02:51 am (UTC)
I know! Or, "Thank you for letting Future Me be more lazy."
(Reply) (Parent) (Thread)
[User Picture]From: perligata
2010-03-08 03:06 am (UTC)
One of my friends has this problem all the time. He's a contractor and has to keep track of how he spends his time and regularly has problems with listing his activities because when he goes back to his notes, it's like:
- apache stuff
- network
- ntp stupidity

Which at the time he thinks will be enough of a hint for him to remember, but in practice is almost always insufficient. For my part, I've got didiwiki running on my machine and try to write in it frequently for any TODOs or outstanding bugs (that don't belong in the bug tracker, also a good place to document) or what have you, with as much detail as I can handle writing. It has saved my ass many times.
(Reply) (Parent) (Thread)
[User Picture]From: lindseykuper
2010-03-09 03:24 am (UTC)
It's probably a good thing nobody ever looks at my commit messages, because more often than not, the message for filename is something awesome like, "Worked on filename".
(Reply) (Parent) (Thread)
[User Picture]From: perligata
2010-03-09 04:24 am (UTC)
I have a bad habit of writing haiku, myself. Luckily the nature of my work precludes the need for well-documented commits.
(Reply) (Parent) (Thread)
[User Picture]From: mindstalk
2010-03-08 05:06 am (UTC)
Congrats on Chinese Rooming your job? :p
(Reply) (Thread)
[User Picture]From: lindseykuper
2010-03-08 05:17 am (UTC)
You should see what I'm working on for Amal. It consists entirely of moving symbols around on pieces of paper. They have meanings...but it's easier if you don't think about that.
(Reply) (Parent) (Thread)
[User Picture]From: oniugnip
2010-03-08 04:46 pm (UTC)
!!

We have the movie ...

Do you like low-budget indie films with interesting premises culled from things you've spent a lot of time thinking about? With some exceedingly creepy acting, that suggest a really good movie that could be made, but is left as an exercise to the viewer?

Would you like to borrow it?
(Reply) (Parent) (Thread)
[User Picture]From: lindseykuper
2010-03-08 06:11 pm (UTC)
I'm kind of shocked that Damien wasn't among the people who came over to watch the movie that one time.
(Reply) (Parent) (Thread)