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.

Read on →

Guilty Developer Syndrome

I've noticed that when developers have worked on a project and then someone else takes it over, they seem to feel guilty about decisions made on the project. When I ask them why certain decisions were made, they might sheepishly say, "Yeah… I know it's not the best way to do this, and it's not the way I would do it now." Some might get defensive, or cite external constraints like schedule pressure. But my belief is that developers should not feel strongly negative about older projects.

Experience

I'll admit that I got a mulligan. It was a Ruby on Rails project for an internal tool. I hadn't worked with that technology stack much before. I kind of hacked something together based on the requirements, and it worked fine. There were few tests, and the design definitely did not use best practices. But it worked.

Read on →

Pecha Kucha Complaining

If you absolutely must complain, I have found an interesting, and perhaps socially acceptable, way to do this. There are a few concepts that separate my method from ordinary complaining.

Pecha Kucha

Pecha Kucha is a challenging presentation format where presenters have twenty slides shown for twenty seconds each. Presenters are forced to practice and consider what they will say and how they will transition between sections, and are promptly jerked off of the stage after their time is up.

Complaining

If you can change your situation, change it. If you can stop yourself from complaining, don't complain. Always consider these first and consider your underlying assumptions again. What seems out of your control is often in your control but outside of what you let yourself believe. Considering complaining about your relationship or your job or your house? What larger problems are under the surface, and what can you do about them? Even if you don't believe you can change your situation, you can likely change your attitude about it.

Read on →

TODO: FIXME, HACK, and XXX

I was wondering what people's standards for using tags in comments like TODO, FIXME, HACK, XXX, and the like were.

// TODO: implement the foo module here
...
// HACK here be dragons
...
// XXX
...
/* FIXME:  late at night, I need some sleep */
...

One advantage of using these tags is that they are easy to search for and give an understanding of where the code can be improved. Most IDEs even have a special view to look for these kinds of things.

Read on →

How to Use Meta-information Effectively

There are numerous attributes that contribute to effective continuous learning and meta-learning, among them:

  • where I found something
  • how I found it
  • who recommended it
  • how long ago the information was published
  • the context of techniques
  • how surprising the information was to me

I contend that this meta-information is actually more valuable than the information itself.

It's helpful to think about these attributes to get higher signal streams of information. When I find that a particular blog or person has interesting content, I listen much more closely to what they have to say. While I don't turn critical thinking off, I don't need to spend as much time considering the source. Links and ideas presented from a trustworthy source tend to be of higher quality. Finding a good source of information makes it much easier to get good information in the future.

Conversely, remembering meta-information allows me to debug and debunk things that I have come in contact with. When I start to disagree with someone whose opinion I previously agreed with, I also think critically about other things that they said or thought. Perhaps there are other views that they held that are also incorrect, and I'm basing my thoughts on this incorrect information. This helps me realize when my mental models need to shift. Everyone has a bias, and I want to make sure that I understand their bias and that is it not harmful to me. If I realize that a much-read software pundit just started selling bug-tracking software, I might start to examine the quality of his articles because of a potential conflict of interest. Similarly, if I understand that the last time I read about something was five years ago and believe my information be out of date, I might preemptively decide to brush up.

Read on →