Log in

No account? Create an account
What documentation is good for - Lindsey Kuper — LiveJournal [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.


[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)