I will be trying to keep my own (though a bit more light/free form than that in the link) in order to bring a bit more structure to my day-to-day.
Do you have any experience with developer diaries? Have they helped you become a better developer, and if so, what kind of effects did you notice?
What finally made it into a working solution is writing plain markdown files, one per day, automatically synced to bitbucket via tiny bash scripts that initiate a new file for the day (aliased to 'j' for minimal hurdle to start writing), opens them in an editor, and committs to the repo after closing the editor.
It is available here: https://github.com/samuell/mdnote
The nice thing with markdown, if you make a level-1 header for each new file, is that you can concatenate the file into a long file, and run pandoc -i allnotes.md -o allnotes.epub, and get a formatted and searchable notebook for offline use, when you want to read it, with the Level-1 headings denoting chapters - so, one chapter per day!
(I have a script for this too of course: https://github.com/samuell/mdnote/blob/master/as_epub.sh).
I start the day with:
% note (which just runs Emacs on my notesfile)
and M-x new-day
which just appends the current date to the file and positions the cursor, all ready for typing. Dirt simple.I used to have macros and whatnot for carrying forward lists of TODO items and important tasks, but that was overkill and keeping things simple seems to be the key to success. Likewise, apps like OneNote and so forth just got in the way and wanted to own a piece of me.
I have a man page repository that is just a simple folder that gets tab completion (basically ls fed into the complete function). aliased to `mm` as in myman(pages). that gets opened up into emacs though so it's basically a repository of files that you can grep through.
Care to share your emacs/shell setup for what you are doing?
Everything goes in one big "scratch.txt" file, with headers like:
###### Saturday, May 20 2017
...at the start of each day. These are generated by a function I run every day: (defun new-day ()
(interactive)
(insert (format-time-string "###### %A, %B %d %Y\n")))
"scratch.txt" is always an open buffer in Emacs. You can search through the file with isearch, helm, or whatever you use. I use the "desktop" library to save and restore all open files when I close Emacs.That's really it, just one big unstructured text file.
I don't put a lot of prose in this diary. Only todo items, code snippets, and errors / log output.
Our setups have slightly different goals: yours is to create daily nuggets of documentation, while mine is to archive whatever thoughts and code were running through my head each day.
The problem with applying a bunch of structure is that you start to screw with the structure, maybe try to turn things into JSON or whatever, pivot by date or technology or location, and a few hours later you've wasted a bunch of time mucking with stuff that you'll probably waste more time mucking with later. Just slamming text into a file and having a minimal syntax for dating things is, I've found, sufficient. I want notes and a little support for continuity ("what the heck was I juggling when I left on Friday?"), not a blog or a platform for deathless prose.
It'd be nice if there was a rich text system similar to Emacs that didn't force you do write markup or handcuff you to a proprietary data format. Truthfully I haven't looked that hard (multi-platform is probably difficult to achieve). I have notes files strung back over twenty years, and simple text is a hard habit to break.
My team also do standups on Slack, and I've got into the habit of writing detailed Slack stand up bullet points with links to commits, documents I've created and so on - almost a semi-public developer diary. I don't check back to these very often myself, but they do spark some useful conversations.
I've also gotten into the habit of writing extremely details commit messages - often multiple paragraphs for a few lines of code change - that record the background and reasoning that lead me to the change. I do most of my code reading through the GitHub web interface, frequently referring to blame and history, so the more context I can find for historical commits the better.
The way I write it is similar to test-driven development — I write down each step in what I'm doing before I do it. When I run a command, I copy the command itself into my notes, then once it's run I copy the important parts of the output (e.g. any error messages).
It really comes into its own when I want to pick up on a task that I had put to one side a few days previously, or when I run into a problem that I think I'd encountered before. It also makes it much easier to avoid the trap of trying the same thing several times before you realise that you're going round and round in circles.
It's also useful for writing documentation. You can just copy and paste what you've written in your lab notes into your commit summaries, Jira tickets, e-mails, spec, help files, whatever, then tidy up as appropriate.
I think searching works well when you are as month or maybe three into the project. How does this work like after five years?
If you organize by topic, you have to decide which topic to put information in. This means you have to pause and think for 10 seconds about your organization system before writing anything. 10 seconds is enough to lose your train of thought.
If you organize by time, you don't have to decide where to put it. It always goes in "today". You have to pause for 0 seconds.
The last technique especially helps me a lot. When thinking through a hard problem, type out your thoughts in a semi-structured way, never deleting anything. Makes it easier to deal with problems that can be too large to hold in your head at once, to think about the aspects of something step by step, or to retrace your thought process and see why you made certain decisions earlier and maybe explore a different route when you get stuck. When finished, it can be used as a foundation for a design doc I share with the rest of the team.
I can't believe nobody made this already!
This creates a feedback loop for stress reduction where I aim to mitigate both the likelihood of having a crisis and train a calm response by learning how to deal with smaller stuff so that the day is full of 1's. I chuck it all in a text file once a day, and return to it because my todo is also in there so I always have a backlog. I don't distinguish between work and hone tasks although I might if I were going in to an office.
Long form diaries I don't really engage with because they'd sap relatively more time - I would get caught in trying to make it a storytelling experience.
A nice side effect is that weekly status meetings are easy.
A simple markdown formatted file is more than enough.
I have headings as: "Working on", "Will be soon working on", and "Worked on" to mark my ongoing, todo, and done tasks.
Why ?
I noticed after 43h in a moving window of 5 days my focus, irritability is up to the roof and I make way too much mistakes that can lead to a dramatic mistake.
My work contract is 37.5 so everytime I reach too much overhead I talk to my manager ask him if he will need me one day to make extra efforts in case of emergency?
He says yes, I say I will abide but if we are working under normal load, than he needs me to rest and give me my time back.
He then picks on me, saying it is my responsibility to not stay to long at work, I make him notice it is because of the company management I have to stay late and the deadline.
He grumbles says it is not the right time.
I go to see the CEO say the same thing
They give me my family time back. I stay quite rested (add 2h30m / day (when the rail company has exceptionally no problem) of commuting with the worsts train lanes of Europa (1M commuters/days)) so it actually feels like commuting is working. Teleworking is denied for lack of control.
Oh! and lunch time is not counted as worked hours except for the other managers. (so I stay away from my family 10hours per day, I see my wife 5 hours a day).
That is the only diary I am keeping.
If I get overworked/burntout, it costs nothing to the company, but I will certainly get fired sooner or later and have a hard time finding a job with a sort of depression running.
Ideally, look for a job with a smaller commute or better attitude to remote work, and get out now. If you can't do that and need to stay in this job for a while, think about changing your mindset to empathise with your managers, even if you dislike them. Be helpful, think about what they are 'actually trying to achieve', which might not necessarily be what they asked for. Remember this is only a stepping stone til your next, better job.
If you're never going to like working 8-10 hours a day you need to figure out the necessary stepping stones to move into working for yourself.
But whatever you do, don't spend years in a me-vs-them mental battle with management at your current role. I made this mistake and deeply regret the lost years (though I did teach myself JavaScript in that time so now I'm massively employable, fuck that employer, har).
My thought would be that if you can manage a way to increase that 43h by just 10% or 20% then over time and transport delays will not be as worrying.
Can you incorporate stretching exercises or walking into your work environment? Try and keep a diary of the positive things that can help you cope with work.
I mostly used plain text files for it, and I never found a web solution that did what I wanted. So I wrote my own a few months ago during a time between jobs: https://www.masongup.com/DailyNotes
Kinda similar to what some other people on this thread seem to do. I always used plain text files for simplicity. IMO, thinking about formatting and making things pretty just gets in the way. The point is to get all of the details of everything you did that day down for future reference. That's what my site does too, just plain text notes, no formatting codes supported, stuffed into a DB and searchable.
Works pretty good for what I need. I've been meaning to add some more features to make it easier for other people to use, but haven't gotten around to it yet. Feel free to use it if you want, it does have import from and export to text files.
Currently, I'm sort of split between three tools. Omnifocus (a GTD manager) for tracking all the tasks, quiver for notes through the day, and then I use [emergent task planner], a paper based task planner for the days tasks. As much as omnifocus/gtd helps me track things, I found using paper to block out each hour of the workday ahead of time really helps me focus. If I find myself losing focus, I can refer to that and (usually) get myself back on track.
After I moved to a full time role in my chosen industry, I had less time to focus on personal projects and less motivation to keep blogging regularly. I try to keep up with it but blog posts are few and far between now so I would no longer call it a diary.
The only standalone artifact I keep, though, is an excel spreadsheet tracking rough office hours, project, caffeine consumption, and choice of lunch. This helps me reassure myself that I'm not slacking off (especially when I'm considering a short day), a top level rough timeline, keep my caffeine intake in check, etc.
https://github.com/wishinghand/Today-I-Learned
They're not deep or very in depth, but I leave them public in case someone needs what I discovered.
I got the idea from someone who posted their version on Hacker News years three or four years ago. Theirs was more journal like in its disclipline- the author added one a day.
I find it really handy to figure out how your thought process about the project has grown over time.
Earlier I have used google docs for the purpose. Though those documents were often more structured than the link I shared above.
Something that is yours and walks out the door with you, every day.
When the system or someone starts to screw you, such a record can be useful and actually viewed with some validity. Better yet, can be meeting minutes and internal communications that document the situation.
There's a reason Comey is known for writing memos about problematic situations.
What I do keep is a large file of projects or snippets of projects, sometimes with extensive notes.
I refer back to these frequently to see how I did something or look at code samples.
But, as time goes on this has become a bit of maze to wade through. I spend time trying to remember what project it was etc. etc. Grep helps a bit :). It would be better to organize this somehow. Not sure I'm interested in a full blown diary though. DRY.
The context of discovery is often not relevant for the context of fix.
It's available for every platform.
You can create checklists. You can share anything from your mobile with trello so I keep track of everything I read.
Initially I kept notes in Evernote, but eventually switched to Quiver (http://happenapps.com/).
like any other diary, you won't re-read it and if you run into an issue of which you know you've faced it before, chances are that your written down thoughts are that unstructured that solving the issue for a second time probably takes less time than trying to find the solution in your notes.
so if writing down the issues you're facing and their solutions makes it easier for you to remember, go for it, other than that such a diary is of no use to my opinion
Share the wealth! :)
I use tiddlywiki.
What is important to me:
1. Page per Day and Event I have a page in a wiki per day and one for each event that happend on that day. A event may be an idea, an issue to solve later, a link to an information, etc. By having each event as a single page with an URL, this piece of information is easy to share via messenger or email or can be mentioned from other places. Within the wiki I create a new page for the day in the morning and add child pages for each event I assume may be of interest in the future.
2. Document vs. Record Since our wiki stores information more reliably than my brain, I need to write it down. When I discovered the difference between a document (needs to be updated) and a record (needs not to be updated), the organization of information in our wiki got much easier. Records come in form of events and are part of the journal. Information that is central and important on the long run (most is not), is part of the wiki in form of a topic space.
3. Multiple Views with Tags I also tag most of the events. Since each tag also has its own page where all pages are listed where this tag occurs, I get multiple views on the journal. One form of tag is the "subject" that maps the event to a project/product I'm working on. Others (and there are only a few) simply categorize an event as an "issue" or an "idea". Some also have a tag related to a subject I'm currently working on. When I come back to the - for instance - "issue page", I can see, what I wanted to have fixed not today, but by "the end of the week". If I think to remember to have had a great idea last week - but fail to remember what it was - I head to the "idea page" (to see that it was usually not that spectacular as I thought in first place). The tagging may cost some seconds, but it makes it easier for me to track fields of interest (by text search) and find related information (by browsing).
4. Structure for Speed As others have mentioned, it is also important for me to get the information into the journal quickly. Therefore too much given structure may be an enemy. None the less I use a template/form to put information (such as the description or links to related resources) in separate, always the same (name and location on a page) sections. For me this is actually much easier than to start with a blank page.
5. Copy-Paste for Speed I also need to paste screenshots, files, and URLs quickly to a page. Therefore I choose a wiki that supports this over markup files in a repository (which are great for other use cases with other requirements as others already have mentioned on this page).
Not everything runs as smoothly as I want it to be. So there is always room for improvements ...
BTW: I'm one of the authors of the mentioned article about developer diaries (https://www.smartics.eu/confluence/display/PDAC1/Developer+D...).