6 ms·

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 th

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).

simonw 6y ago
+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 https://github.com/simonw/til
southphillyman 6y ago
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.
ra7 6y ago
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?
- chadlavi 6y ago
  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.
- stevekemp 6y ago
  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__via_emacs.html https://blog.steve.fi/keeping_a_simple_markdown_work_log__vi...
- deleted 6y ago
  [deleted]
chrsstrm 6y ago
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.
- kanyethegreat 6y ago
  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!
  - chrsstrm 6y ago
    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.
PascLeRasc 6y ago
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.
whoisjuan 6y ago
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.
- mvanbaak 6y ago
  Instead of putting it as comment in the file, put it all (including graphs etc) as commit message when you commit the feature/fix
- owl57 6y ago
  > 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.
afc 6y ago
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.md https://github.com/alefore/weblog/blob/master/zettelkasten.m...
- koolba 6y ago
  That’s amazing! So the linkages for the visualizations are derived from the notes themselves?
  - afc 6y ago
    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.md#extracting-articles 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_commands/lib/zk.cc 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-correctness.md https://github.com/alefore/weblog/blob/master/software-corre...
- masklinn 6y ago
  Seems very similar to the structure of Notational Velocity, though I don’t remember whether NV provides easy cross linking between notes.
- elliotec 6y ago
  I love this. I've been wanting something just like this. Thank you!
kanyethegreat 6y ago
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?
nunez 6y ago
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.
motor_wolf 6y ago
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.
Izkata 6y ago
OP mentions vim, so I want to add to this that I use vimwiki for this purpose: https://github.com/vimwiki/vimwiki https://github.com/vimwiki/vimwiki
lloeki 6y ago
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 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.
RMPR 6y ago
Org-mode ftw
caviv 6y ago
I have read somewhere: Code comments are like love letters to your future self :-)

simonw 6y ago

+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 https://github.com/simonw/til

southphillyman 6y ago

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.

ra7 6y ago

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?

chadlavi 6y ago
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.
stevekemp 6y ago
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__via_emacs.html https://blog.steve.fi/keeping_a_simple_markdown_work_log__vi...
deleted 6y ago
[deleted]

chrsstrm 6y ago

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.

kanyethegreat 6y ago
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!
- chrsstrm 6y ago
  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.

PascLeRasc 6y ago

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.

whoisjuan 6y ago

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.

mvanbaak 6y ago
Instead of putting it as comment in the file, put it all (including graphs etc) as commit message when you commit the feature/fix
owl57 6y ago
> 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.

afc 6y ago

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.md https://github.com/alefore/weblog/blob/master/zettelkasten.m...

koolba 6y ago
That’s amazing! So the linkages for the visualizations are derived from the notes themselves?
- afc 6y ago
  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.md#extracting-articles 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_commands/lib/zk.cc 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-correctness.md https://github.com/alefore/weblog/blob/master/software-corre...
masklinn 6y ago
Seems very similar to the structure of Notational Velocity, though I don’t remember whether NV provides easy cross linking between notes.
elliotec 6y ago
I love this. I've been wanting something just like this. Thank you!

kanyethegreat 6y ago

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?

nunez 6y ago

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.

motor_wolf 6y ago

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.

Izkata 6y ago

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

lloeki 6y ago

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 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.

RMPR 6y ago

Org-mode ftw

caviv 6y ago

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