Hacker News Reader

Comment by chadlavi | Hacker News Reader

KEEP NOTES. Write everything down. Write down what you were thinking about, how you felt about decisions, things you tried for bug fixes. you never know when this stuff will be useful to you again.

I keep really basic markdown notes in a git repo, roughly one file per day with an ISO date name, but some things I give a separate file name (still with the iso date, but with some descriptive words) for things that might be good to re-access or are part of a series of similar notes (like a TIL file or a recurring meeting with the same person).

View on HN

I do the same, using the Zettelkasten method. I've found it very useful. I write many small notes as markdown files and link them together, storing them in a git repository.

I wrote a bit about Zettelkästen (and the practices I follow), in case others find it useful: https://github.com/alefore/weblog/blob/master/zettelkasten.m...

That’s amazing!

So the linkages for the visualizations are derived from the notes themselves?

Aww, thank you!

Yeah, that entire article is generated from the set of notes. There's one note for each subsection (down to the finest level of granularity) and it just extracts the article directly based on the links. I described this in a set of notes that end up here: https://github.com/alefore/weblog/blob/master/zettelkasten.m...

The images (e.g., distribution of back links per file, semilattice view, etc.) are also just generated programmatically from the repository of notes.

The code that extract it is here: https://github.com/alefore/edge/blob/master/rc/editor_comman... (function zke, which receives the output path, the path to the initial note, and a string listing space separated paths of notes to ignore).

Here's another example of an article generated from my notes (this is way longer and is very incomplete, and probably contains a bunch of mistakes, but you may find it interesting as an example): https://github.com/alefore/weblog/blob/master/software-corre...

I love this. I've been wanting something just like this. Thank you!

Seems very similar to the structure of Notational Velocity, though I don’t remember whether NV provides easy cross linking between notes.

The first thing I do for every project is set up a development blog. Hugo + a nice free theme + Gitlab Pages + Netlify CMS. Everything is contained in Gitlab and I can keep the Pages site private and only accessible by members of the repo. It is less of a daily log and more exploring "issues" - basically anything I took time to research and figure out. I'm very adamant about recording details like dates, version numbers, context, code snippets, commands, and URLs of resources used. It all comes down to asking myself, if I see this issue again in the future, what information do I need to easily solve it without opening 40 browser tabs? At first it takes some effort to circle back and write the post after you solved the issue, but after a while I found myself writing the post concurrent with writing my code. The Netlify CMS isn't the most beautiful UI but being able to just write markdown in a browser window eliminates having to keep a git repo locally. Organizing with categories and tags makes referencing published posts easy and if you want to get fancy you can integrate Algolia for search. Honestly, having a project dev blog has saved me so much time since I don't need to keep every detail in my head anymore. Being able to go back and read about why certain decisions were made or how I overcame complicated problems is absolutely invaluable. And of course having this rich documentation while on-boarding new team members or passing the project off to someone else makes everything easier. Setting up a dev blog is 100% worth the minimal effort it takes.

I've been doing this for years, and even though basically no one reads my blog, it's nice to have a place where I put "polished" thoughts about my projects.

I love this. I have a grouping of pages in Notion for tech notes. But I really like the idea of scoping it to a project. I like that you don't need a local repo. I'll have to experiment with this. Have you automated anything for it? And do you have any patterns you use (eg. organizing the information, etc). Thanks!

There's really not much to automate. The Gitlab CI/CD config file to build Hugo and publish to Pages is always the same so I just re-use it as boilerplate. Likewise the Netlify config is usually the same as well, so once you've learned that syntax and structure it's not much work to put in place. I always like to peruse the latest Hugo free themes before I start and I usually end up using a new theme for each site anyway. The only real patterns in terms of organization is making sure I categorize and tag each post in a detailed manner. Most issues are related to a certain piece of the project or tech used, so when you know for example that your issue is related to the database then you can look at all posts categorized or tagged in a similar way to see if you already addressed the issue. I do find the most helpful step I took was making sure the post had a nice meaningful title with the proper keywords - that helps keep you from reading multiple posts until you find the one you need. Hugo and Gitlab's CI/CD are really great but the open source Netlify CMS is the key to making this setup so easy and remote only.

I tried to do this for my last project but ended up spending too much time making the blog and didn't get around to properly starting the project! Maybe instead of rolling my own site from scratch I'll use Hugo.

A similar idea I practice. After I solve a complex problem I usually leave a big comment at the top of the main file, explaining how I arrived at that solution, the caveats, how it works, and how it interacts with other files and dependencies.

If I need to, I also use Monodraw to produce ASCII character graphs and add them to the comment to explain concepts.

It helps to cement the solution in your brain and it's a system of record on how it was accomplished in case you forget.

I do this only for personal projects though. I don't think co-workers would appreciate an essay with exhibits at the top of a file, lol.

> I don't think co-workers would appreciate an essay with exhibits at the top of a file, lol.

Why? I don't really have an experience of being a co-worker, but I have always appreciated such essays in free software.

Instead of putting it as comment in the file, put it all (including graphs etc) as commit message when you commit the feature/fix

+1 for notes. I make really detailed notes in issue threads when I'm working on things. I recently started keeping a TILs GitHub repo and it's already proved useful. https://github.com/simonw/til

I want to take notes everyday, but I keep getting bogged down by how to organize those notes so I can "look back" efficiently. Essentially, I want to avoid taking so much notes that I'm reluctant to search for something because I haven't organized it well. Do you think the ISO date name method is working well for you?

It's mostly for sorting and context. I just do a straight up search (in my case in vscode) across all notes when I want to find notes about something particular.

Really the most important thing to do is just start taking notes. You can reorganize later if you need to.

I just have a simple header for each day:

   # 09/05/2020
   Today I mostly ate cake

   ## Discoveries
   ## Meetings
   ## Projects
   - Worked on project 1
     - Fixed issue <link>
     - TODO: Bugfix #1234
   ## Misc

So a fixed set of headers for each day "Projects", "Meetings", "Discoveries", "Misc", and free-form text. Sometimes I copy/paste commands and output.

Searching is pretty much just grep.

More detail here https://blog.steve.fi/keeping_a_simple_markdown_work_log__vi...

Seconded. I finally skipped endlessly looking for the perfect note system and just created this stupid 10ish snippet of shell:

https://github.com/lloeki/dotfiles/blob/master/shell/notes

   note foo # creates a note in vim
   note # lists notes in vim’s netrw

Since note file names are time stamped, they’re sorted and I don’t have to care about dupe names. It defaults to creating as .md but renaming the file afterwards doesn’t matter.

It’s so dead simple that I use it all the time instead of fantasising about the perfect note system.

OP mentions vim, so I want to add to this that I use vimwiki for this purpose: https://github.com/vimwiki/vimwiki

I use org-mode in emacs for this! I usually keep notes on whatever task I am working on, and more general programming notes which I file into tagged headlines for easy reference later.

Yes. I wish I did this years ago. I’ve been doing it since January but there are so many things on my resume (and elsewhere!) that I’ve since forgotten and it’s annoying.

I use a combination of WorkFlowy and Notion for note-taking. WorkFlowy serves as my daily quick jotting medium. Notion I spend more time crafting and organizing, so that knowledge is more discoverable. Do you ever find yourself going through these ISO-dated notes? I would image re-finding something is difficult?

I do this too, and I use Sublime to generate HTML from Markdown, so at work I have hosted guides like commonly-used SQL queries for one of our projects or documentation on how I updated our OpenSUSE and built a specific version of mariaDB we needed. It's been pretty great.

This. I'm having some difficulty remembering details of systems I worked on and bugs/approaches I took at places I no longer work at. Going forward I'm going to document details about everything I do, a personal post mortem of sorts.

I have read somewhere: Code comments are like love letters to your future self :-)

Org-mode ftw

Reply on news.ycombinator.com