Using a logbook to improve your programming(routley.io) |
Using a logbook to improve your programming(routley.io) |
So the author says that it's a good idea to write logbooks, and that it will help. But no mention on how it would help, and what would you actually do with them after you write them up.
A few concrete examples would have been nice.
If the idea is to help you solve the problem more efficiently, why should it be formalized? as opposed to scribbling notes on a notepad that you throw away at the end of the day.
- Consider the high-level goal; can it be completed immediately? if yes, do it, otherwise break it into smaller parts.
- First part is usually some kind of research. If it's a bug, it'll be a reproduction. If it's a well-specified feature or a refactoring, it'll be locating all areas of code that need to be updated. If it's design, it'll be an initial sketch.
- Subsequent parts depend on the task at hand. For a bug, I generally try and work through to a minimal set of reproduction steps. For a feature, it'll be a generated list of tasks that came out of the research step.
- When working on any given task, I add sub-entries in the form of a dialectic. For a bug reduction, I come up with a hypothesis, then try and prove or disprove it by testing. For design, I propose one approach, then consider the implications; then another approach, and so on. For a feature, tasks generally get added for any "todos" that crop up as I implement things, to ensure I complete everything.
I essentially record salient details of my internal monologue to ensure that I can pick up context again easily, and generally fit more into my working memory by offloading it into text.
I reckon it made me perhaps twice as effective an engineer, particularly in distraction-prone environments. It's also made me a lot more confident that I'm not relying too much on memory as I get older - not that I think I forget much now, but I believe I won't be very dependent on a large working set.
If I concentrate, I can sense something akin to the typical "internal monologue", but it isn't present enough to be copied down, and even when it is it tends to move so fast that I only really get the conclusion.
"It helps you focus on the task at hand by providing immediate context on what you’re doing. If you forget or become distracted, you can quickly get back to your train of thought.
"It helps you learn quickly. You can observe your method for problem solving, see what works and what doesn’t and make improvements."
Saying "no mention on how it would help, and what you would do with them after you write them up" feels inaccurate to me (although the observation about the lack of specific examples is correct).
To me it is an accurate description, as the author focuses on what he believes are the results while not presenting any tangible example or framework on how to get them.
In short, without any information on the "how" this blog entry boils down to a page and a half where the author states that he believes that writing down things he is doing in no specific way and following no specific method may help him in some way. Well, good for him.
It doesn't solve all problems, e.g. a complex problem that is hard to understand are not a good fit; if I notice that what I write is lengthy or that I keep returning and restating it, then this is that kind of problem; here I normally leave the desk and try to sketch it on paper.
Very seldom I look through the file to find why I've made a particular choice; I don't think logbooks are of any use here, it's better to document the design elsewhere, closer to the product. I'd say logbooks are write-only (although they may be a source for the docs).
I suspect it is ninety percent confirmation bias. Looking back at successes and assuming something in common of all of them had to be contributive.
Not claiming it is all luck. Just saying that outside signals usually bear more meaning than given credit.
The first step is to describe the nature of the problem as well your planned solution before beginning. I think this can be a pretty powerful practice in being mindful.
All to often I find myself jumping into a half-baked solution while at the same time having only half-understood the problem.
This is what kills me in tech interviews. Unfortunately its hard to calm down and think quietly when you are being hounded by the interviewer to "think out loud".
I've been opening up Jekyll in the morning as the start of my day. I write the blog post for the work I'm about to do. I've noticed that I'm getting better at explaining the problem clearly and the solution. When there is a paragraph that feels out of place I yank it into a different file immediately to get it out of the current flow of the post. The paragraph felt out of place because it was probably a distraction from the problem Im trying to solve today. Also, the great thing about this technique is that I have a blog post at the end of the work day that I can look back on and say, "Damn, I shipped something" if I didn't feel like I shipped anything else (common problem in our field of software developers)
Before lunch, or a meeting, or end of day, or when someone interrupts me and needs something, or any form of break, I "serialize" what I am working on in the journal, and then I read it when I am coming back.
In this way I can keep my mind clear and focus in the next activity.
It is also useful for standup meetings, retrospective meetings, etc... when you often need to describe what you did yesterday or this week.
I like to structure my programming lab book in a similar way, for every task/ bug/ project I try to jot down a description, hypothesis, expected outcome and document my progress with code snippets / outputs / plots. I also keep a Todo list at the top to visualize my current workload. It really helps if you have to come back to a problem later on or just to get a good overview of your current task. I feel lik this also works nicely in conjuncture with GTD to increase my productivity.
Here's how I use my own flavor:
1) I create a GOAL. The GOAL is my ultimate big picture, which will give me immense happiness. So, the most recent example is, I wanted to build an E-Commerce application.
2) I map out the PATHS to achieving my GOAL. So, what I consider PATHS is:
a) What programming language should I use? b) Which APIs should I use, Paypal or Stripe to accept payments[1]? and so on...
3) I follow a flavor of DDD[2] to come up with the important modules I need to have for a functioning E-Commerce project.
Examples: I will need a Order Management module, I will need a Marketing module (for sending emails, running campaigns). I will need a CMS module to host product pages.
4) For each of the modules, I will create an issue on Github and add a checklist[3] of the stuff I need to get done.
5) Everytime I make a commit, I will reference this issue and the tasks along with it. Eg. "Removed Paypal #12"
6) At the end of the week, I will review the commits and evaluate whether this particular method I used was worth it. A good use case would be experimenting with a library and comparing it with another - Eg. Bootstrap vs Semantic UI. I will use the learnings from this workflow in my future projects.
7) I will also see if something can be automated. For example, for my current E-Commerce project, I use Phoenix/Elixir. It has it's own set of scaffold generators, but they're opinionated (they use Bootstrap). So, for every project I got tired of replacing bootstrap and customizing the generated scaffolds. So, I wrote a custom generator that drastically saves me a lot of time for large projects.
Hope this helps :)
[1] Not sure why anyone would use PayPal in this day and age tho.
[2] https://stackoverflow.com/questions/1222392/can-someone-expl...
[3] https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-...
1. Write down the problem
2. Think real hard
3. Write down the solution
4. Write down how well it worked
5. GOTO 2
I do something similar using org-mode, and it's useful when, after some time has passed and I need to do the same thing again, I can go back to my notes and not start from scratch again.
Recommend the vim-wiki plugin for this https://github.com/vimwiki/vimwiki; in any vim-window the logbook for today is accessible via [leader-W-leader-W].
But than again, there was TED talk of all this organization is ultimately shifting the energy from actual. Which led me reducing number of 'productivity' application and sticking with a few.
Wunderlist Onenote Evernote - mainly for the phone.
Some more concrete suggestions from what appears to be the university of Idaho's Electrical Engineering department can be found here:
http://www.ee.uidaho.edu/ee/power/jlaw/COURSES/CAPSTONE/F05/...
Go ahead and try this:
Put,
alias lb='vim ~/logbook/$(date "+%s")'
Source the bashrc.
Run the lb command. It creates a new file with a different epoch timestamp each time. This `lb` command doesn't need to be a bash function. It can be an alias and work just fine.
Maybe how this works in zsh is different...
It doesn't make sense. If you do
alias e=vim
The only way to have a "precomputed" alias is to get the quoting wrong, and leave $() in double quotes instead of single quotes, meaning it will be evaluated before the alias is even assigned.
alias lb="vim ~/logbook/$(date '+%Y-%m-%d').md"
:exec ':e ~/logbook/' . strftime("%Y-%m-%d.md")Some features that make Org useful for this:
- I'm clocked into the task so I can always jump to it easily, even as I hop around other emacs buffers
- supports code snippets with formatting in any language
- it's easy to add timestamped notes or write in free form
- can export the subtree to HTML or Markdown or Latex/PDF, to share with others
- GitLab will apply basic Org formatting (as with markdown), so I can share them directly just by pushing
- supports regex search across all agenda files, regardless of where they are. This is nice if, say, I know I had a similar issue with e.g. some docker command but don't remember which project it was on
https://news.ycombinator.com/item?id=4448361 has some good tips and tricks.
function lb() {
today=$(date '+%Y-%m-%d')
fp="/home/you/logbook/${today}.md"
if [ ! -f $fp ]; then
echo "# ${today}" > $fp
fi
vim $fp
}----
journalfile=$(date --utc +%Y%m%d-%u.md);
if [[ ! -f $journalfile ]]; then
echo "# "$(date "+%A, %e %B, %Y") >> $journalfile;
git add $journalfile;
else
echo "File already exists: $journalfile";
fi;
vim $journalfile;
git commit -m "Changes in journal file $journalfile" $journalfile;
git push origin master;
----
Source: https://github.com/samuell/mdnote/blob/master/editnewjournal...
For more structured documentation, I keep separated text files for each solution that I can easily find if I need it later.
EDIT: Also, scratching your plan with pencil and paper before implementing it helps a lot.
- What work was done for the day, yes you might use something like Jira but a journal can be also good at the same time
- New things you learn.
etc etc etc
Work done for the day for me is typically captured in commits or bug updates - that way my colleagues can easily take over if I win the lottery or are suddenly taken ill.
And stuff I learn is learned, so I don't need to write that down :-)
Working in a team, shared information is critical and logbooks just aren't the best way to achieve that.
All of them have open data formats so you’re not locked in and can save everything in git which are requirements for me.
I use: Oxford Black n' Red A5 Matt Casebound Hardback Notebook, and UM-153S Signo Impact Gel Pens. I get through one of those notebooks per year on average.
Edit: https://rwmj.wordpress.com/2017/11/24/keeping-a-work-noteboo...
I rather have files that I can understand later, and easily grep as a bonus...
(I do admit that crossing done tasks on a piece of paper feels very good.)
That plus a nice fountain pen [Lamy Safari 18.7USD], ink [J. Herbin Perle Noir 7.2USD/30ml], mechanical pencil [Lamy Safari 12USD], pencil leads [Uni Nano Dia 0.9USD/20leads], technical pen [Rotring Isograph 16.3USD], and I've got a nice little setup.
I've found that using a text editor that supports code folding, and following a markup language that enables the text editor to automatically set fold points, helps navigate log entries more efficiently.
I also use a notebook to jot down tasks, but when a job requires a high number of different unrelated small tasks that are completed rather quickly I've found that a physical notebook actually makes the process very inefficient.
It's the meta also, it is capturing the models mentally and ideas and notes. This reduces cognitive load, and actually by making notes increases the chances of you remember something.
> And stuff I learn is learned, so I don't need to write that down :-)
Hey if thats the case then fine, but generally memory deteriorates, recall becomes more difficult and the details change.
> Working in a team, shared information is critical and logbooks just aren't the best way to achieve that.
Log books are not generally for the team, they are for you.
But as you say each to their own.
This. I never enjoyed drawing diagrams in Inkscape, though my boss swears by it.
I’d much rather draw with pens on paper and then digitise by scanning.
When I started coding, as a teenager, I'd pace around the room explaining things to myself almost as if I was giving a lecture, so it's fairly baked into my thinking process. If you assert something, laying a statement out there, the process of hearing it can cause you to start to think other things: is it actually well-justified, are the assumptions behind it solid; what are the consequences and implications of the statement; all the things you might think if you heard someone else say something, and you're listening critically and intently.
If you use a text editor you don't need to write everything down right away. You can just dump a keyword or a snippet that describes or is associated with what you're doing, note your intent and/or your goal, and as you work on your task keep updating your notes whenever you get the time.