Documentation formats and speaker interviews

In lieu of actual content on this blog, allow me to introduce you to some recent posts I’ve done for Opensource.com:

A changelog for the company?

"How to achieve Inbox Zero after the holidays" by CommitStrip. Used with permission.

“How to achieve Inbox Zero after the holidays” by CommitStrip. Used with permission.

A few weeks ago, Mathias Meyer shared an article that suggested a “Do Not Disturb” feature for Slack. At my job, Slack has become our main internal collaboration tool. It hasn’t quite killed email, but it’s pretty rare for members of the engineering team to send internal emails these days. It’s a great tool, but it can be hard to keep up with if you’re away for an extended period of time. This is particularly true when important messages get lost among jokes and gifs.

After being out of the office all of last week, I came back to several hundred emails and thousands of Slack messages. There was no way I could get through all of them, so I declared Slack bankruptcy (and deleted the emails that were for tickets someone else handled). I just have to trust that if there was anything important, my colleagues would fill me in. But is there a better way?

When I worked at McDonald’s, we had a management log book. It was a simple three-ring binder with hand-written notes. Mostly it was used by the store manager to communicate important information to shift managers and supervisors, but any of us could leave notes for things everyone on the management team needed to know. At the beginning of each shift, managers and supervisors were expected to read new entries and initial them.

I would go off to college for a semester and when I came back during breaks, the last few months of log entries were easy to catch up on. Obviously, they didn’t contain all of the changes, but at least I knew what the major changes were. It helped me come up to speed quickly, which was especially important when trying to lead teenage fast food workers.

I am a major proponent of work-life balance, both for myself, and for my team. It benefits neither the employee nor the employer to have people working all of the time. But it’s hard to fully disconnect when there’s a fear of missing out on important information. Perhaps a company changelog is in order?

This could capture important announcements, product decisions, unexpected lessons, and other things you really want team members to know. This allows people to declare bankruptcy when needed without missing key information. It doesn’t have to be anything fancy, a shared text file (in reverse chronological order) can be sufficient. Whatever works for your team.

Odd touchpad behavior in Fedora 22

A few days ago, the touchpad on my HP 2000 Notebook PC began acting up. It would jitter around a lot and insert phantom mouse clicks. My desktop ended up with approximately Avogadro’s number of Notes widgets. At first, I thought the touchpad was going bad. I resigned myself to a life of using a USB mouse, at least until I could buy a replacement.

As it turns out, though, it appears to be a software problem. On a whim, I opened up the KDE System Settings. When I selected “Touchpad” from the “Input Devices” menu, I saw a warning message that the saved settings did not match the current settings. Clicking “Apply” fixed…the glitch. Hopefully this helps if someone else comes across the issue. I didn’t file a bug because I don’t know what changed or how to reproduce it.

Book review: Bourbon Empire

Those who know me well know that my go-to drink is bourbon. “Take glass, insert whiskey” is my favorite cocktail. I’m hardly a connoisseur, and I don’t consider myself particularly well-educated on the subject. When I heard about Reid Mitenbuler’s Bourbon Empire: The past and future of America’s whiskey, I  thought it sounded like a good way to catch up.

Although the book is an examination of the history of American distillation, it lacks a dispassionate tone. Mitenbuler clearly enjoys bourbon, though he presents both the highs and lows of history. The use of humor in the narrative makes the reading experience more like a conversation over a glass of whiskey than a lecture.

That’s not to say that this book couldn’t be used in a history class. Bourbon did not develop in a vacuum, and Bourbon Empire discusses the effects that law and bourbon have had on each other over the centuries. Prohibition is, of course, the obvious example, but the practices of the whiskey industry were an important part of getting the Pure Food and Drug Act passed.

As a first book, Bourbon Empire is an exceptional result. My only complaint is that it ended much too quickly. The stories behind bourbon brands are rarely as interesting as the marketing department would have you believe. Nevertheless, Reid Mitenbuler weaves them together into a complex and enjoyable experience worthy of a terrific bourbon.

Bourbon Empire is published by Viking Penguin and is on sale now.

RIP Paul

I swear this won’t become a theme (or at least I hope it won’t), but the world got a little bit darker today. My friend Paul Birkhimer passed away this morning after a a brief battle with cancer. Paul was diagnosed with pancreatic cancer at the end of May. It was aggressive, but it did not dampen his spirits.

I’m not sure Paul’s spirits were dampenable. I didn’t know him half as well as I would have liked, but he always seemed to be the most cheerful person in the room. His cheer was a quiet one, subtle. He wasn’t bombastic in a way that turned people off, but an even, slow-burning cheer.

I first met Paul because his wife Suzanne of my undergraduate department’s Assistant Head. I’d seem him at department functions and thought he was a pretty fun guy, but I couldn’t remember his name. I called him “Mister Sue” until I learned his name. I don’t remember if I ever told him that or not, but I’m sure he would have gotten a kick out of it.

Paul faced cancer exactly how Paul would: with humor, with faith, and with the love of countless family and friends from all over. Would that we were all a little more like Paul.

Selecting an open source license for VC funding

Tomasz Tunguz recently had a post exploring the relationship between open source licenses and exits (either funding or acquisition). When I first saw this, I was excited. The practical consequences of license selection is an area of particular interest to me. Sadly, the article was terrible.

Tunguz compares funded project license distribution to total open source license distribution. This is a fatal flaw since there is no evidence to suggest that these are drawn from the same population. Many open source projects are small hobbyist efforts. Even large ones can be predominantly volunteer-driven, with no intention of seeing venture funding or acquisition. That alone is enough to render the comparison meaningless. A better study would examine projects looking for funding and see if any license is correlated with better results.

The article is titled “Which Open Source License Should Your Project Use if You Want to Raise Venture Capital?” but fails to answer the question. It does not even establish whether or not the license selection matters. Even if a full statistical study wasn’t feasible, commentary from a variety of VCs could help provide guidance.

Licenses are chosen for a variety of reasons. Some are philosophical, some are practical. Choose the one that fits your project best. If that means finding out which licenses the VC firms you’ll target prefer, do that. If it means using the license that’s common to the ecosystem your project lives in, do that. Just don’t rely on a few slapped-together bar charts with no credibility.

How I take notes

I’m not what you call an obsessive note taker, but I have learned over the years that I shouldn’t rely on my memory without some kind of external backup. A while back, I came across an article about how taking notes by hand is better for long-term memory. This immediately made me sad, since all of my serious note-taking is done digitally. The more I thought about it, though, the more I realized digital notes are best for me.

I first started taking digital notes late in my undergraduate career. I had a program called “GoBinder” where I could import course notes and slides and comment directly on them, as well as adding my own free-form content. This worked fairly well for more text-based classes, but for meteorology classes with a lot of Greek letters and illustrations, it was a bit of a challenge. I mostly stuck to hand-written notes.

Years later, I went to graduate school. A master’s degree in IT project management is very wordy, so I resumed digital note-taking. Pretty early on, I settled on using Markdown. This allowed me to take notes that looked like text but still have some basic markup so I could highlight important points, make lists, etc. When it was time to study for exams, I would review the notes, and convert them to HTML for more in-depth study and review.

This method worked pretty well for me and had a few added benefits. When doing homework, I could `grep` for a key phrase if I couldn’t remember where to find it. Also, the files were on my SpiderOak account, so they were available to me anywhere. I didn’t have to worry about leaving my notebook at home or spilling coffee on it (at least if I spilled coffee on my laptop, I’d be able to get my files onto a new one).

For me, the portability and searchability are compelling reasons to stick with digital notes. As the article points out, I do find myself doing more transcription when typing than when writing, but that’s a habit I can fix.

RIP Lara

lara

Internet, I want to tell you about my friend Lara Ann Harrison. Lara was a short little bundle of happy. She was a sweet person who was fiercely loyal to her friends. I met her by happy accident. Her older sister was my age. We met at a couple of Model UN conferences and became friends. One day, I called her and we talked for several minutes before I said “you don’t know who this is, do you?” Well it turned out I didn’t know who she was. I wasn’t talking to Kari, I was talking to Lara.

At 17, I didn’t have too many friends who were younger than me, but Lara and I quickly became close friends. I hope I was as good a friend to her as she was to me, but at that point in my life I don’t think it was very likely. At any rate, we lived about 45 minutes away from each other, so we didn’t see each other too often, but we talked a lot on AIM.

I got older and busier and we started talking less. Then she got older and busier and we talked even less than that. The last time I saw her was at least 5 years ago, probably closer to 10 at this point. I don’t remember the last time we talked. We just sort of drifted apart.

I found out earlier this week that Lara died at the far-too-young age of 28. In fact, she died back in January. I missed the news when it first happened, and it was only because Facebook had decided to show me a post that her sister made that I realized she was gone. It’s odd how the Internet has changed the way we interact. Without it, Lara and I would never have become close friends. Without it, I might never have known she left us far too soon.

Working from home

A couple of months ago, Harvard Business Review ran an article about working from home. The article didn’t say telecommuting is the worst, but it did point out some of the productivity and morale benefits of office interactions. After two years of my own working from home experience, I thought I’d reflect on my own opinions.

The thing that has surprised me the most is how much I miss having a commute home. Whether by bus, bike, or car, my trip home took 15-30 minutes. It was my time to switch from work mode to home mode (and if I were riding the bus, watch some Netflix). My commute home now is the two seconds it takes me to stand up and leave the room. If I’ve had a rough day at work, immediately walking into a 4 year old and a 1 year old (and a wife who has been herding them all day) doesn’t allow for much time to reset.

I do sometimes miss the personal interactions with my coworkers. I have a colleague across town, and I see him in person once every few months. On a normal day, the fact that I can work without someone sitting in my office distracting me is a benefit. When I do need to talk something out, coworkers are a video call away. I really only miss physical presence on days when I’m just not feeling very motivated to work.