How to Write a Work Journal

My friend Tyson works at a major insurance company. Recently he shared with me a technique that he uses there: He keeps a work journal to write down domain-specific things that he learns.

Journaling could include writing down a technique or rule of thumb used, a page of a book that was helpful in a certain area, or who to contact in a different department in case of questions in a specific area. Sometimes it could be something that went particularly well so that he can look back when times are tough and remember a time when he persevered. Other times it is something that didn’t go as well as he hoped. He also does this to clarify his own knowledge so that when he needs information he has a place to look, and for potentially transferring that knowledge to other people.

I recently tried experimenting with this technique. I suppose that I like writing, so this came somewhat naturally. I liked separating this from other writing that I do because it seems useful to have it all in one place. I am just capturing knowledge that I have gained from working on a project. Writing this down regularly is really helpful in writing documentation later because you explicitly state what you have recently learned. This prevents me from being blinded to what I learned and taking it for granted. It might be obvious to me at the end of a project why the build works the way that it does, but along the way I needed to learn a lot of things and make various decisions. So this seems to be a good way of documenting decisions for later understanding and analysis of results.

Here’s an example of something I wrote (sanitized):

20100203 - 1531

While a PDF is printing to file (which is an excellent way
to save paper), let me recount how I added a new
HelpPDFBuilder to the application.  I modified the
HelpApplication.exe.config file pursuant to the rest of the
file.  I added references in the code to the new class.
Then, I expected everything to work.  However, the changes
in the HelpApplication.exe.config file did not get picked up
by the application.  The problem was two-fold.  First, I had
commented out the post-build steps, which meant that the
config file did not get reexamined.  I uncommented these,
and it still didn't work.  The next problem was that I did
not then copy the newly touched config file to the bin
directory.  This process is clumsy, and it would be nice if
it was improved somehow.

I would say that this document should probably contain things that I would be fine with anyone reading. If I have a beef with a coworker, I should probably talk with them about it or write it somewhere more private. This just ensures that I am writing things down that are actually useful and won’t bite me in the rear some time later.

Documenting things moderately well also helps me because the next person knows more and has fewer questions. The insurance company mentioned actually has a process for transferring responsibilities on projects. Also, at the end of someone’s career there, they have a process for sitting the person down and doing a knowledge transfer exercise by having different people interview them. This seems quite interesting. It seems like a really good way to not lose information and has the side effect of validating the person’s career there and allowing them to tell stories that will live on for some time to come.

The key here seems to be writing things down that seem obvious in retrospect but are difficult to acquire. It doesn’t need to be in a complicated format (mine’s a text file) or take a long time. Maybe five or ten minutes a day of the most important things you learned would be of immense value when you or someone else comes back to a project in a year’s time.

Does anyone else use something like this? What did I miss?