Keeping a Changelog at Work (2020) | Hacker News Reader

Keeping a Changelog at Work (2020)

code.dblock.org

162 pointslawgimenez61 comments

I've adopted a practice like this at times, and it definitely helps, but then there's also those days where it starts with a standup, you get pulled aside after to help someone wit their changes, then there's a production issue, then your manager needs some data for an exec meeting, then... and you're left at the end of the day trying to piece it all together. Ironically those are the days where it's most useful to have had something like this, but I've never figured out the balance.

I agree 100%, it's hard to keep this kind of thing up

For me, it is the opposite: I can't work without writing down todos in org-mode. Granularity may vary: I start from 2-4 todos per day and write down anything that I can't do write now (2+min tasks) throughout the day (org-capture). If the work is smooth, several hours may pass on a single TODO heading, if I'm stuck, I can drop to individual "- [ ]" list items, to mark the progress. It helps with extending working memory and having the immediate feedback helps with executive function.

No-thought generous fibonacci effort estimations help detect if some tasks take too long (emacs nags in mode-line) and I need to regroup e.g., split the current todo into sub tasks.

The changelog is generated automatically (from the org-clock-in tasks) by Emacs (org-agenda).

I feel like I have the worst of both worlds.

I can’t work effectively without a todo list, but I have extreme trouble keeping with the habit.

It helps to write down every task that won't be solved immediately, before doing it. This is also great when you're doing multiple things in parallel.

Almost like keeping a personal write-ahead log. :)

Not quite. A write ahead log memorializes the final state of the outcome. It should be everything you need to recreate the result or net effect.

if you write it down before you start, it’s more like the intent.

As a remote worker, it would be really cool to have something running locally that had access to my Zoom logs/meeting transcripts, Slack, email, calendar, etc.

Then take that and have it summarized what I did all day on the computer.

This is technically what Microsoft Recall promises to do and no one is happy about it.

Isn’t it also what Apple Intelligence promises to do?

No, IIRC Apple Intelligence does not make such claims. It can keep context within interactions and know about information in some of your silos. Recall has a much bolder feature set in that it wants to beware on everything you see on your screen.

The point of many tasks like this is in the doing. Writing throughout the day what you are working and planning has an effect on your focus and productivity, in and of itself.

Automating this kind of thing is automating your own defeat.

I use Manictime for this. It keeps track of active applications, you can add tags and it can take screenshots at defined intervals. https://www.manictime.com/

Simple, just write everything down. Making a quick note takes about 12 seconds. I make about 8-9 quick notes to summarise all tasks in the day. Everybody has that amount of time to do it, EVERYBODY.

There is some cognitive burden (Find the note app, decide how to store them, remember to open it) but if you do it for about 20 days it just becomes second nature and habit.

I have day by day notes, for everything I have done and things I've discovered, going back about 8 years now. Every single day, because it only takes 1-2 minutes a day to write them. If you turn this into a habit the mental context switch cost tends to zero.

It has been a great source of links, notes, reminders, everything, I see it as my digital memory.

I've found that the simpler the system, the more likely I am to stick with it! I tried a complicated org mode setup, automated obsidian plugins, and others but what ended up being the most effective for me was just a very long bullet point list in notion! I simply added headers for each month.

"Simple" but not always easy. I have executive function / working memory issues so that cognitive burden you mention can be untenable. My solution is to lower the load/latency of the note-taking. I have a hotkey that pops up a text box where I can jot a note, it shoots that to a file, then I organize it with a TUI at the end of the day (or whenever!)

If you have one of these workdays, do you feel that you have actually accomplished anything notable in the changelog? I find that it is very hard to "sell" this electron-cloud-like helping out behavior when you have an assigned task to complete, both to myself as well as management.

Have I accomplished anything brag-worthy that day? Not really, but having the list helps on two grounds. One is to have an explanation of what was considered important enough to derail that, so I can look at trends (e.g. Am I the only person on the team who knows about X so I'm getting derailed by questions about X? Maybe it's time to revamp the X docs or give a presentation on X). The second is placating stakeholders elsewhere in the company. "We didn't do that thing you asked for yet" on its own sounds like you just don't care about them. "We didn't do it yet because of incident XYZ123 impacting $xxxK in revenue needed to be fixed" usually works better.

I always keep very sparse notes with pen and paper. Once the dust settles, I transcribe them in full sentences into my digital journal.

This act of reconstructing a coherent narrative from disparate events is an enormously useful part of writing the journal.

I have played around with various methods (OneNote, personal wikis, Markdown, etc.), but I have found that keeping 2 primary plain-text personal notes has helped me a lot, preferably with Notepad++.

1) A simple text file with important information, with everything including logins, host names, how-tos, even things like team members’ names and roles. I rarely change anything and often just add information while marking previous obsolete info as such.

2) A simple TODO list that I just keep adding to. Many times I will get requests that aren’t necessarily tracked in project management tools (either there’s something that can’t be encapsulated in a user story, or the overhead of putting it into the software is just too much).

In addition, IMO too much has been formalized into disparate systems and can easily get lost or difficult to access. Keeping personal notes like this enables me to have much more control and allows me to easily search the entirety of my knowledge base with a simple text search or even regex.

Edit: missed a few words

I do this myself, but I keep it strictly private. I’m mindful that while this record keeping has been very beneficial to me, it could also be wielded against me in ways I don’t anticipate.

I guess it depends on what kind of work you do, and perhaps your personality and career goals too, but if I ever found myself working in a place where a simple, factual log of the work I have done was weaponized against me, I'd immediately start looking for a new place to work.

We live in an era where companies are trying to claw back data (open APIs) that were made public with altruistic intentions and is now being used in ways they don’t like (LLMs). Obviously not directly applicable here—no one is training an AI on your logs. But my personal policy is rooted against oversharing. You can’t use the data in ways I don’t anticipate if you simply don’t have the data. If I’m doing the work to produce that information, I am going to ensure that it used is entirely to my advantage.

Any kind of work, most sprint reviews are basically: what can we do better so that we can squeeze more out of you than last sprint.

That's oversimplifying things a bit.

Not OP, but I also keep a private log.

Simply put, different things go in there, compared to a public one; let alone a public one with intended visibility.

And some of the most useful logs are the most private ones.

Plus, not sure how much I'd trust a person's public logs if I knew they were made to be both public and publicized. My expectation in that scenario would be that actions were embellished / inflated accordingly. Everybody has on and off days, but I'd be very surprised to see this openly admitted in a public log; after all, what good could ever come from it?!

I used to go through my daily logs at the end of the week and pick the most important, non-personal, work-related things that happened in the week, and add them to a separate weekly log. This I was happy to open in public in the middle of a conversation if necessary ... but I would never open my private log in front of anyone. It's too private.

The value of private isn't as much that it can't be used against you; but that you don't have to bother with the cognitive load of sanitizing it.

I currently use a plugin that opens up a Daily Log each morning as I open my editor; and populates it with a template

ToDone: * ToDo: * Blockers: *

First thing I try and do each morning as I catch up on email/overnight test results is fill it out as an outline of talking points before the daily Standup.

Throughout the day I try and keep a running list of task I work on down int he daily log; often with comments like 'why the everlovingfuck did jason delete the prod db' and a general summary of problems and how I solved (or didn't solve) them.

Outside of a personal knowledge database, when review time comes along it makes it much easier to summarize what I've worked on also.

I've done this at some companies, and for some consulting engagements.

The last company where I initially did it, I stopped, because I found two problems with how I was doing it:

* spending extra time to track this information that was usually already captured somewhere in a project tracking system; and

* sometimes siloing information, when all the redundant reporting means that sometimes one place got the information, while another place didn't (so, sometimes it was only in my separate notes, which weren't discoverable).

One time I didn't do this was in an early startup, when I was the entire engineering team. I ran a low-friction GitLab board in a Kanban variation, for pretty much all work I did. All information was in GitLab, in one way or another. At our weekly update meetings, I screenshare the GitLab board, and point at the top (most recent) boxes in the Done and Abandoned columns (and Active and Blocked), as I summarize. If anyone wants more info, either then, or at any time in the future, one can click, and it's there.

One thing that doesn't cover is if I help someone with something without creating a task for it. If you have a bigger company, and it cares a lot about performance evaluation, then you might want to have a convention of mentioning someone who helped, in the comments on a task. Then a manager can have some report, over the entire task&project management system, that gives them more insight into how everyone has been contributing. (Personally I'd prefer to be at a company where no one has to even think about performance evaluations, because they're too busy focused on success of the company, but the info is probably there if anyone wanted it.)

I've done something like this for a year or two with a single Markdown document + Obsidian. I call it my "working set" where I write down my TODO list. I have a similar document for my personal life when I have a lot going on or when I'm trying to be particularly productive.

At the end of the day I make an entry for the next day carrying over what I didn't finish. If something has been carried over for too long (e.g. something that I'd like to do but isn't required) then I just remove it. Usually I might have 3-4 tasks each day, though when I first joined my most recent company my list was something like 10-20 small tasks for a couple of weeks.

If I have larger investigations I'll always write it down in a separate Markdown document so that my working set doesn't grow too large.

It's a very low overhead way to do task tracking, and there are all of the benefits listed in the parent article. I don't think I'd ever make this publically available though.

I use the Obsidian Task plugin, so if I had an important, low-urgency idea at the end of the week instead of rolling it over I will give it a START or DUE date. Then I use the task query to keep an eye on when to reconsider or finish things.

This works a lot better for me, instead of copying over more and more ideas each day, or building a write-only SOMEDAY.md

I do something somewhat similar which has evolved for myself and in part for my team. What follows is heavily abridged in the interest of time.

I use Obsidian as follows:

1. Daily log in bullet-point format. Title in YYYY-MM-DD format. Bottom of log has [[YYYY-MM-DD]] with tomorrow’s date.

If I get into a task that starts to get a bit ‘chatty’ and/or would benefit from capturing stdin/stdout/stderr snippets, I’ll use the [[blah]] trick and dump it there.

If a particular priority task didn’t get tended to, I copy that into tomorrow’s daily before stepping afk for the day.

Gets shared with manager, etc.

2. Weekly summary using the ![[Week ending YYYY-MM-DD]] embedded view Obsidian feature in my daily log page. For that at-a-glance warm fuzzies. This boils down to:

- retrospective - highs - lows - 1:1 notes - incoming week’s tasks/priorities

I use this page for my 1:1’s of course. I’ve only very recently started copying the retrospective to my manager via Slack to ensure he’s got the goods.

I prep my incoming week with a new weekly summary, and pre-populate the bare bones for the daily notes.

> Since my first day in AWS, just over a year ago, I’ve been experimenting with keeping a CHANGELOG of everything I do, available for everyone at the company to see. I think you should too!

I think this is a great idea for CEOs and those overly eager juniors, but for everyone else who's not trying to speedrun work burnout any%, that's the stupidest idea ever. Seriously, what's the goal here? Suppose everyone in your company does this. The result is that employees get divided into three camps:

1. Those who don't give a fuck about their jobs and have exactly one entry per day. For them, their CHANGELOG (don't forget obligatory capitalization) is basically a document that their manager can pull and have them fired for low performance, even if the manager was satisfied with their performance before this metric was introduced.

2. Those who don't give a fuck either, but understand the point above and don't want to get fired: they'll start filling their day with useless tasks, just to look busy. There's no added performance, but management becomes more difficult, because employees are incentivized to lie to their managers, making communication murky. The majority of employees fall into this category.

3. A clique of employees turning their CHANGELOG (again, don't forget the obligatory capitalization of all letters of which the word consists) into a badge of honour and a competition. There will be one winner, the rest will feel bad about being bad employees and low performers, and having this pointed out.

It's basically a diet version of that software that takes a screenshot of your display every five minutes and sends it to HR. And turns that into a publicly available graph.

I have been doing this for years and it’s amazing. It really does make meetings more useful because I can show people what I’ve done and they see it and know. It’s far easier in the moment to put down the Jira ticket and write a description of what I did or who I helped or what is broken and the attempts to fix it etc etc.

It helps me organize what I’m going to do. Who I need to talk to. Etc etc. this part is outside of the Changelog per se but I also keep a log for that and I keep a document called reference. It’s a Knowlege graph of sorts of all things that I learned about the company over time.

Examples include: this is how to reload data from this really convoluted system and the things to watch out for. (This eventually becomes a confluence doc for everyone’s benefit)

I use jrnl (jrnl.sh) to keep a daily work journal. I start every day writing about the most important things from the day before. My journal entries are comprised of a headline followed by a short blurb. It’s easy to script with jrnl, so I can easily pull out just the headlines of the last week or year, easy to search for colleagues names, etc. Comes in handy during annual reviews or researching history of decisions. And it’s encrypted.

I have also written about my "worklog" [1], what I call my own changelog at work.

It's a simple Markdown file, versioned on my own Gitea instance.

The worklog contains all notes about everything I spend my time at work. That is project work, meetings, discussions, todos, long-term todos and investigations, and anything I need to be able to check back later.

I cannot count the number of times I went back and searched this file to find information that others forgot, the meeting notes did not capture, and in general things that I need.

Keeping this kind of log makes performance reviews trivial too. Just scroll through the worklog for the period you want, copy paste bullet points, and then spend some time cleaning them up and rewriting them as necessary.

If anyone does not keep a worklog, start now :)

1. https://www.lambrospetrou.com/articles/the-worklog-format-1/

I'm keeping a detailed log of my activities in orgmode. But only because I have to input the hours in another system. It is interesting that even though the categories summarized are from the org-clock-table, I write small descriptions on each category for each day. For instance I might have multiple entries throughout the day for "Client X - Report", but I summarize what I've actually done in the notes. At the end of week I export it and archive with the clocktable along it, using a narrow-subtree. I also paste them in an archived section with the Year/week so I keep track of the activities and they are searcheable. So far, the clock tables themselves have been most valuable to me, especially for review purposes. Still, I believe a brag document complements this quite well and is something I plan to restart doing.

I do something like this and it's helpful.

I tend to forget about a task once it's in the past, so I just put one line per task in a text file every day. Sometimes it would be the same line ("2024.12.21 Worked on xyz feature") for several days in a row, but at review time, it was easy to see what I'd accomplished.

Is not a personal knowledge base like Trilium[0] a simple solution for storing digitized memories of your life? Rather than being limited to one lines because of the .txt file format? Paragraphs can contain more information than one lines, you know.

[0]: https://github.com/zadam/trilium

in the first scrolls of the README, I see a note about this project being in maintenance mode and then two huge images about how much they support Ukraine.

not really what I want to see from a piece of software that's supposed to store all my knowledge.

notepad.exe, gedit, nano, vi, notes.app

boom, a piece of software where you can store all your knowledge. stop trying to make this political, can we have one friggin place where folks don't express a political opinion in an attempt to stir up shit?

this OP is about keeping a changelog at work, how do you do that?

In my case, it's not a limitation. I just wanted a reminder of what I'd been working on (and maybe "FIXED!" when it was done).

My personal diary is a Word document.

I use Obsidian for this, it has a button that quickly creates a daily note: https://help.obsidian.md/Plugins/Daily+notes

After a while I review the daily notes and delete or categorize + summarize them into subfolders (e.g. "Work", "Project XY", "Feature XY").

Kinda related to the theme, but looking for other perspective. Having a brag document is a really useful way to track those things too:

https://jvns.ca/blog/brag-documents/

I keep track of everything i do in excel privately too. I have a log like that since my first job, dating back a dozen years.

I use some basic conditional formatting to highlight today's tasks. I write down everything I do. Small assists and unplanned work are added after the fact. Each row had a do date, a project tag, and notes such as reminders of who to contact about it.

This helps me be extremely organized and not forgetting any tasks even down the road. I also keep track of pet projects and identify good times to work on those. Also made me way better at guesstimating how long something will take and spread out workload from upcoming busy periods more.

This has made it trivial for me to prepare weekly stand ups, quarterly business reports and yearly reviews. The only downside is I can't keep it up when I'm really overworked. Those periods stand out as several week gaps in the task tracker. I just lose the granularity but i still know which project was problematic using high level roadmaps and notes from retros/5 whys - so i can add a basic note for the period about what projects i was working on at the time. I have a simplified changelog like that for personal projects as well.

i keep a very simple "notes.txt" file and just append to it; i add a timestamp at the start of every day. literally no other formal structure

i put nearly everything in it that is interesting. snippets of code, bits of debugging sessions, notes from meetings, little reminders. it's a single file that my editor loads in milliseconds and it's very searchable

i've been doing this for over 35 years (... starting over at each new company). having a "dump" of knowledge at my fingertips has saved me hours, many times

I like this. Very low tech. I distractions. No fluff. Just text. Amazing. I use obsidian but I find myself always spending time trying to tweak it. And it gets nowhere other then me spending unnecessary time on it.

The article really lacks a discussion on the granularity of this “change log”. Do you write “worked on db project” or do you detail progress and failures?

I keep a daily log at work (not public) and sometimes it just says “project 1, project 2” for days on end. Not really useful to look back at, but still nice to jot down in the morning.

I send my task list along with notes to chatgpt to summarize, and log the output. It's easy to go back to the date where I did something and find detailed notes, based on this generated index. The problem is dealing with days that are full of interruptions and are basically completely unplanned. I have trouble tracking these.

I keep weekly notes in my work Org Roam project, Week-N-of-2024.org, where I store all the current work. At the end of the week I carry on TODO/DOING/WAITING headings. Every heading usually references topical Org Roam notes, so checking backlinks I can trace the work progress.

To keep it public - I tag certain headings with :Priority: tag and then use Org-QL to find them, pretty-print (enrich with Story links , completion date), sort by priority, TODO state etc; then export to HTML and copy-paste into Confluence.

The trick is to balance between granularity of items. I definitely don’t want to make everything public, but I do want to have everything in my notes, and this method solved it - the best of all tried over 15 years.

I do something similar, and in fact have some useful bash scripts to help me remember to log stuff.

Basically it's a script that pops up a reminder window at regular intervals, with options for daemonising, and enabling/disabling while daemonised, and auto-enabled at startup if it's a new day.

Plus, it integrates with a pomodoro timer/logger I've written, such that all the "tomatoes" (i.e. pomodoro sessions) I've done the day before automatically get added to the log at the start of a new day.

They're fairly simple scripts, but happy to share if anyone's interested.

I have myself started practising this at the beginning of this year when I changed job. I have all my notes in git repo as well as a changelog file. But changelog is more like a timetrack file.

In repo I have also commit.sh script [1] (for which I have also desktop shortcut) and at the end of work day I simply run it and (after a few more confirmations) turn of laptop and go home.

[1]: https://gist.github.com/jurakovic/8c0535b3b8fbc96228de1a94ea...

I really enjoyed Snippets at Google which was a company wide way to share your changelog.

There were also some nice integrations to pull in commits, doc edits , etc..

This is a great idea. My problem is one of discipline ... to do it every day. And I dont know if that is a problem that can be solved by technology.

If you know you're not able to do something every day, design a process that does not require that you do it every day. "Discipline" is overrated: a way of people blaming themselves for their inability to solve anticipated problems with in-the-moment, resource-intensive strategies that nearly everyone is instinctively averse to, and thereby validating their disinclination to pursue structural solutions.

That's why I like https://www.timely.com/ since it records my activities automatically

I would recommend not using pixelation as means to hide text. It is easy to reverse.

Is it? I hear that thrown around a lot but I doubt it's easy. Maybe people are confusing it will a swirly filter, which isn't destructive and can be reversed easily?

I know that there's strong prior knowledge but the pixelation is destructive so the problem is very ill-posed.

Fair enough, I haven't tried it myself, just glanced over a piece of software that does it (HMM) and saw the blogpost.

In reality , though, removing just a bit pf entropy can be of great value when context is known. With LLMs in mind.

It's not necessarily easy, but possible in some cases. If you can can live with a risk of, say, 1% that someone reverses this, fine. If not, I recommend using black bars.

> pixelation is destructive

Yes, but JPEG compression is destructive too yet you can (well, most of the time) see what it's in the picture.

With pixelation you are essentially replace a clearly readable character with some yet unknown 'pixel character'. It's even more pronounced on a fixed-width fonts.

Just try it yourself on the clear shot (not a JPEGed to death one) first.

Personally, if I wanted something to not be read by anyone I would never leave it in the source image and pixel blur it out. That doesn't make sense. Why leave the original text there at all? Cut the entire area out so there is no text, and nothing that can be reversed in that cast. I'd even take it a step further and say that once you cut the text out, screenshot the image and use that instead of the edited original, that way even embedded edit/undo/smart os features can't accidentally leak out the ability to undo to the original.

Funny. I was doing the same guided by some gut feeling, and then the Pixel vulnerability was published, where people would recover original images from the images cropped in Pixel album app

Reply on news.ycombinator.com