Engineer's Logbook
Nov. 11th, 2015 12:34 pm![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
jacklogbook
fanf linked to an article about this, I can't remember where now, but I wanted to talk about keeping a logbook. I think most people do something similar in some way, but I don't know if everyone thinks about it the same way. About three years ago, I noticed that I didn't always remember things I needed, and it was a problem, and I started keeping the simplest possible solution, which seems to have done fine so I still have it.
I use a text file (backed up, and in a separate source control system just in case I ever want to fish out anything I've deleted, tho' that doesn't seem likely) as a diary or logbook.
Every code change goes in source control, but almost everything ELSE goes in the diary. Notes on where such-and-such server is, and who to ask for log-in details. Results from a series of experiments. Dead-ends investigated and abandoned. Steps to install something that I'm likely to need again in 18 months, but I don't know if anyone else will need.
Brief summaries of conversations with people, suggestions, etc. Informal deadlines, comments on other projects I don't officially need to know but it's likely useful to be aware of. A summary, entirely for myself, of what I've done today, at whatever level of detail seems useful (sometimes just, "closed off several dead ends, nothing else useful", often "did X, Y and Z. need to finish A and B. Decide if C." Occasionally a more detailed checklist pending being copied somewhere else).
And if anything seems like it WILL be important to other people, it's easy to copy it into a bug report or anywhere else.
what DOESN'T go in there
There's several things that do NOT go in the logbook. Anything that's already in source control commit comments doesn't need to (though sometimes the comments are a cleaned-up version of a longer work-in-progress in the diary).
Personal thoughts, frustrations, introspection, etc, etc, I find it valuable to write down in a SEPARATE file. Thinking through them is sometimes useful, but I never need to refer back to them in the same way.
Immediate TODOs go into another file, although I'm considering changing that. Long-term suggestions go into another file, or into bug database.
Brainstorming is typically on paper, but once I'm thinking of things which are fairly definitely relevant, they usually go on TODO list or logbook.
There's an art to judging what's necessary. I used to write too much. If I've gone down a bunch of blind allies fixing transient problems, I don't usually need to record all the details, just say "after a bunch of faff, realised the problem is X".
Format
You could do something different. Keep a physical logbook. Have a procedure for everything. Organise by topic instead of date. Have a better memory.
But what I do is simple. One long text file. I find everything important by just searching (occasionally I'm slightly redundant to make sure any likely keywords are included in what I'm writing). I have a line ">>>> [date]" in the correct format, a blank line, and then whatever. Usually a short description of what I did. Sometimes a list of things, which are copied to a todo-list or lightly edited throughout the day. Sometimes results of something. Sometimes a useful command line I might need to refer to later.
I never need to skim, I rarely need to say "what things did I do that week", so as long as I can clearly separate days, I don't worry about taking up too much space. If I needed to, I might annotate each day with a split of which tasks I spent time on, but I generally work on projects measured in weeks or longer.
At the top are a few general notes, such as links to servers, internal webpages, etc.
If I worked on significantly different work, I might keep one per project. Eg. for each home project I would have something similar, but at work I just have one for everything related to the company codebase.
Benefits
Anything I previously knew, is generally easily searchable, I almost never have to say "wait, why isn't it working, I had this problem before, why can't I remember what I did"?
If I need to check what state things were in at some time in the past, it's fairly easy to check what I was working on at the time.
It's always obvious what I was in the middle of, I never have to ask "wait, what was I doing on Friday, why did I stop?"
I almost never have to think "I would have written that down. But where?"
You
What do you do?
fanf linked to an article about this, I can't remember where now, but I wanted to talk about keeping a logbook. I think most people do something similar in some way, but I don't know if everyone thinks about it the same way. About three years ago, I noticed that I didn't always remember things I needed, and it was a problem, and I started keeping the simplest possible solution, which seems to have done fine so I still have it.
I use a text file (backed up, and in a separate source control system just in case I ever want to fish out anything I've deleted, tho' that doesn't seem likely) as a diary or logbook.
Every code change goes in source control, but almost everything ELSE goes in the diary. Notes on where such-and-such server is, and who to ask for log-in details. Results from a series of experiments. Dead-ends investigated and abandoned. Steps to install something that I'm likely to need again in 18 months, but I don't know if anyone else will need.
Brief summaries of conversations with people, suggestions, etc. Informal deadlines, comments on other projects I don't officially need to know but it's likely useful to be aware of. A summary, entirely for myself, of what I've done today, at whatever level of detail seems useful (sometimes just, "closed off several dead ends, nothing else useful", often "did X, Y and Z. need to finish A and B. Decide if C." Occasionally a more detailed checklist pending being copied somewhere else).
And if anything seems like it WILL be important to other people, it's easy to copy it into a bug report or anywhere else.
what DOESN'T go in there
There's several things that do NOT go in the logbook. Anything that's already in source control commit comments doesn't need to (though sometimes the comments are a cleaned-up version of a longer work-in-progress in the diary).
Personal thoughts, frustrations, introspection, etc, etc, I find it valuable to write down in a SEPARATE file. Thinking through them is sometimes useful, but I never need to refer back to them in the same way.
Immediate TODOs go into another file, although I'm considering changing that. Long-term suggestions go into another file, or into bug database.
Brainstorming is typically on paper, but once I'm thinking of things which are fairly definitely relevant, they usually go on TODO list or logbook.
There's an art to judging what's necessary. I used to write too much. If I've gone down a bunch of blind allies fixing transient problems, I don't usually need to record all the details, just say "after a bunch of faff, realised the problem is X".
Format
You could do something different. Keep a physical logbook. Have a procedure for everything. Organise by topic instead of date. Have a better memory.
But what I do is simple. One long text file. I find everything important by just searching (occasionally I'm slightly redundant to make sure any likely keywords are included in what I'm writing). I have a line ">>>> [date]" in the correct format, a blank line, and then whatever. Usually a short description of what I did. Sometimes a list of things, which are copied to a todo-list or lightly edited throughout the day. Sometimes results of something. Sometimes a useful command line I might need to refer to later.
I never need to skim, I rarely need to say "what things did I do that week", so as long as I can clearly separate days, I don't worry about taking up too much space. If I needed to, I might annotate each day with a split of which tasks I spent time on, but I generally work on projects measured in weeks or longer.
At the top are a few general notes, such as links to servers, internal webpages, etc.
If I worked on significantly different work, I might keep one per project. Eg. for each home project I would have something similar, but at work I just have one for everything related to the company codebase.
Benefits
Anything I previously knew, is generally easily searchable, I almost never have to say "wait, why isn't it working, I had this problem before, why can't I remember what I did"?
If I need to check what state things were in at some time in the past, it's fairly easy to check what I was working on at the time.
It's always obvious what I was in the middle of, I never have to ask "wait, what was I doing on Friday, why did I stop?"
I almost never have to think "I would have written that down. But where?"
You
What do you do?
no subject
Date: 2015-11-11 03:12 pm (UTC)At work, I do maintain a thing called "stuff.txt", in which I store all those useful snippets you mention – who to talk to about things, what directory on the shared fileserver has something useful in it, helpful example command lines that can be adapted to a general class of useful thing but aren't quite nailed down enough to just put in a script, where the five places are that you always have to update a particular kind of annoying thing. That's a text file, date-ordered, and more or less append-only (but I can go back and edit in forward references, lest I accidentally find a nugget of apparently useful information that's been superseded by a later entry), so it's something like what you describe here, but I don't accompany it with a running narrative of everything I do in quite the same way. It's only composed of those things I expect to want to go back and look for later.
In tricky debugging cases I'll sometimes keep a running-narrative file more akin to what you describe, where I paste in exact commands I ran and their output, interleaved with running text saying what I've deduced from it and where I'm going to look next and why and so on. I mostly find this valuable in cases where it's taking me a while to work out what's going wrong (e.g. anything taking me more than a day to debug), or if I keep getting distracted and losing my mental state, or if it's the kind of problem where I have to keep several confusingly similar things straight. But it generally has the same lifetime as the mystery I'm trying to solve; I don't consider the collection of dead ends and deductive steps to have ongoing value once I know the real answer. It's a logbook for that task.
I think the large volume of free-time stuff I do would make it difficult to keep a single Big Logbook containing everything I've ever known, because at the very least I'd have to keep a work logbook and a home one (stuff involving work confidential material can't go in the home one, and home stuff can't go in the one that I'll lose access to if I change job), and even that wouldn't be optimally useful (surely at some point there'll be a generally useful debugging trick that I need to refer to at home but it so happens I first encountered it at work so it's in the other logbook and I haven't got my VPN hardware token with me at the time ect ect chiz moan drone). But I don't think that's the only reason.