Hacker News Reader

> 1. How much commentary should I write? I try to write not too many notes because I write code, and some say code should be self-documenting. So it's the same old question of how many comments should there be along the code.

I think the best I've heard this was by a friend who said something akin to this;

Programming is the art of solving problems by codifying complexity. Generally, the self documenting part is the 'defining the problem' portion of the code. But in every problem, there's a certain amount of irreducible complexity, or it wouldn't be a problem.

There's going to be some part of the code where you wish you could make it simpler, or you wish you understood it better, or you wish you could break it down into smaller components but there's no 'good way' to do it in the system you're working in. Or, the way you have working is 'good enough' and it's not worth the investment from some (business needs angle) in making it any better.

This is the portion of the code you should comment, and document, and do so liberally and in detail.

Check out obsidian.

It is just folders and markdown so it is ultra portable, but the obsidian editor has tons of useful features like a graph view, autolinking, and a plugin in for anything you can think of.

There are tons of YouTube videos and articles describing different organizing systems and ways to use it.

I like Obsidian, but plain text continues to reign supreme. I prefer nvAlt or my programmers editor, or if on a team, whatever the company provides (e.g. Jira). The embarrassment of options is actually a key problem in itself, since if you do not commit to one, you find your notes spread across various files, tools, and services, totally disjoint in a way that is impossible to work with and difficult to undo.

The ideal tool, which I don't think exists, would combine the immediacy and locality of nvAlt and bidirectionally map to something like Jira for sharing, distributed as a browser plugin and/or a simple server component with local write access.

> you find your notes spread across various files, tools, and services

That is a problem I've experienced too. Therefore I currently write my comments in plain text in the IDE I am using (WebStorm), which saves them as text-files.

I used OneNote for some time but I realized there is a lock-in because it saves its notes in its proprietary format. And now it seems its content can only be saved online on Microsoft servers.

On the other hand if there was a clear rationale as to which type of notes belong to which tool then using multiple tools can actually help you find your note later.

For example: Use your fridge-door for post-it-notes about what food we need more of.

This may have something to do with the "Memory Palace" -techniques. You can remember things better when you can associate a path to finding them. Food? I must write a note about the food. Where should I save it? Preferably close to the fridge, because that is where most food is.

Here's a trick I am using to write my coding-notes: I actually write and save them in files with .js -extension. I can have multiple such files for different aspects of notes. I can write notes about my app specification in one file and code-notes in another file, and what was done and what remains to be done in yet another file.

That means my notes are comments in syntactically valid JavaScript files (which exists only to store such notes).

Now I can use the Expand/Collapse feature of the IDE to collapse all comments to their first line, which is the title of the note.

I can also save real JavaScript functions within the same file and have them syntax-highlighted, so I know the code-examples are valid JavaScript.

I also use a WebStorm macro to generate tags based on current time and/or date. Saving them with the note allows me to refer to that tag from other notes. A bit like hyperlinking, but for text-files.

Obsidian vaults are just folders full of a bunch of Markdown files with a dotfolder that has some JSON configuration files in it. You can probably put images in them, too (I haven't needed to bother yet).

I'm not sure how you can get more plain-text than that.

Obsidian is pretty close to that. Markdown is basically plain text.

I write but never reread. The act of writing helps me organize my thoughts. Maybe I'll reread the last page when coming back to something but that's it.

So my advice is to write when you have a lot on your mind so that you can get it out of your mind. That's it.

Don't mess around with forums. That's for a different problem.

Keep a pen and paper handy always. There can be no barrier to entry or it breaks the flow.

Likewise, I seldom reread. But I do get most out of just writing it down.

It really depends on your work. If you're doing mundane work, keeping notes is just busywork and doesn't really have a payoff.

But if you're constantly trying to solve novel problems, and have episodic ideas that are half-baked, writing notes -- without trying to organize them first -- can be really powerful. For me, I just write them in Logseq and tag them with a few hashtags like #topic1 #topic2 #topic3. It doesn't have to be a perfect tag, just tag it with all the topics you think are relevant.

From time to timeI click a hashtag and revisit all my half-baked ideas -- periodic revisits and curation is key -- I surprise myself when some peripherally connected notes coalesce into a real idea. (Logseq makes this easy because each note is bullet point that can be tagged, and clicking on a tag is like running a query)

This is called the Fieldstone method. (conceptualized by Gerard Weinberg). It's a very useful approach for writers because it recognizes that the best ideas are episodic and don't all come at once, you have to gather the "stones" over a long time before something gels.

https://www.amazon.com/Weinberg-Writing-Fieldstone-Gerald-M/...

I've used it with great success over the years (both at work and in my writing).

Keep trying. Try different methods. What works for me debugging and refactoring distributed systems may not work for you. The thing I tend to drive toward is a single page mind-map-like artifact that is monotonically increasing in density with a focus on system-of-record and data flow. I tend to keep notes about individual tech and important systems in whatever tools are handy, either locally or in a form that are accessible to the team. Often this takes the form of a JIRA page per topic, or an nvAlt note per topic. Tickets aren't great for this because they are ephemeral. These notes are where code snippets, error messages, anything searchable, go. I have something like the Zettlekasten[1] method in the back of my mind when deciding on scope of these support notes. However I may also start from a simple local text file, not committed to the repository, or even attached as a note to a ticket or other ephemeral trigger. But the thing that ties it all together, for me, is that mind map. Once I have that I can truly reason about the system.

1 - https://zettelkasten.de/introduction/

> a balance between "Just do it" and "Write about it"

This is the key point - capturing, organizing and retrieving notes has a cost. And I find myself always paying for notes out of my "just do it" budget. Especially when virtually all of the things I'm working on (notebooks, libraries, applications, planning documents) are themselves a form of writing, having yet another place to scatter my thoughts is not helpful at all. It's much more productive to take that thought and put it directly into the project documentation where everyone can benefit. More README, less journal.

> This is the key point - capturing, organizing and retrieving notes has a cost.

Exactly my thoughts too.

There is a cost. The thing is to keep that cost down to the level where it is in fact a good investment.

I don't think there is an ideal solution. It is just hard work to create information-artifacts, just like there is no silver-bullet for writing perfect code.

I think you need to have a clear separation on what you're trying to achieve. From what you've written, I get the sense that you're combining documentation, wiki and your personal notes together.

For example, code documentation is very subjective. I'd combine code comments with readmes and potentially a separate wiki. All depending on the complexity of it.

For personal notes like reminders or thoughts, there's no need to keep it up to date. It's ordered by date. And when I need it, I roughly remember when I wrote it. If something needs to be updated? Write a new entry today. I use pen and paper for this. This is also where I sketch one-off diagrams and the like.

Separately, I also have a personal wiki for things I learn or teach among other things. Since these are limited in numbers and are quite important, keeping them up to date is not a big task

The problem with writing too much is that it becomes a chore to read, there could be a lot of fluf and a few gems, but you couldn’t tell anyways.

Focus on meaningful, contextual comments that explain the "why" behind your code.

> 2. How do I retrieve a note I've written earlier? I can use tags and search for them but it is not easy to come up with a perfect tag which I would remember later.

Feed them all to an LLM?

I've thought about that. The AI should figure it out. But if I don't know what I should ask the AI it cannot much help me.

I wrote in some discussion about whether AI could replace us programmers? I think they cannot because:

AI has the answers. WE have the questions!