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-26 04:54 pm (UTC)