Hamatti

One time, when I had just started on a legacy project and was struggling to understand how things worked and where the bug was, I printed out many many pages of the code, booked a meeting room for the day, taped the code printouts to the walls of the meeting room and started drawing and annotating.

It helped me see patterns from a birdseye view of the code and see how things related to each other and I eventually found multiple issues that I was able to fix more efficiently at once because I had taken that viewpoint instead of just trying to fix one class or function at a time.

OP here!

That's a wonderful question, sorry it took me over a week to notice it and reply.

A lot of the practical debugging happens with debugging tools on the computer but every now and then I run into issues where it's not obvious why something is acting up. Usually in these cases, there's a conceptual issue, maybe a misunderstanding or an assumption that took me the wrong way.

In those cases, I like to start by writing down my understanding and assumptions of the situation: what is the problem, how does it happen (do I really know how to replicate it), what should be happening.

The act of writing it down (which I call a brain dump) helps me organise my thoughts and often that helps me notice the gaps in my knowledge or understanding which activates my brain to think about the missing bits which often leads to revelations.

> using a notebook is antiquated and we have better tools.

So far, I haven't found tools that beat pen and paper as tools for thinking _for me_.

I still do write a lot of digital notes too but I find that the flexibility of pen and paper — not to mention never having to worry about running out of battery compared to tablets or similar — crucial benefit.

Digital tools might result in better outputs but that's not what my notes are for. I prioritise minimising the friction that's between my thoughts and getting them on paper. On digital, I'm either limited by structure (f.ex. a Markdown file is limited by text being forced into lines) or having to change between tools when I want to jot down something in different format (text, circles, rectangles, arrows, whatever). It's a very small amount of work to switch between them but it cuts my thought because I need to think about the tools.

Pen and paper is the most direct connection my brain I've found.

OP here.

Exactly! So happy to read you managed to pick up the core gist of the story.

It's important to find the tools that work best for YOU.

I partially wanted to write this because I've often felt as an outsider in tech teams where everyone sits at a computer 7.5 hours every day and I'm the one thinking better when I'm away from the screen and keyboard. So I wanted to offer an example to those who are like me and also feel like they might not belong.

OP here.

I don't often do very complex software plans like that. My working notes are often on a smaller scale like individual features or so. If we need to document the full architecture for the project, I'm happy to do that with digital tools.

But while I'm planning parts of it or designing it, I do better with pen and paper. My main issue with many of the digital tools I've tried comes down to the added friction if I need to switch to a different tool in the app when I switch between circles and rectangles and text and the fact that I find free-hand drawing with mouse really difficult.

> OTOH if the plan is very simple and obvious, and can be drawn out in one go, it doesn't really need a diagram in the first place, so I skip spending time drawing the obvious stuff.

I think there's a middle ground where it might be easy to draw on one go but deciding what to draw and how things work together and what's needed requires iterations and for that, thinking through drawing and writing helps me a ton.

I do almost no organising of my paper notes. The only thing I do is that I add a date to the corner of the first page of when I start making a specific note and I keep index pages where I list page/note titles (or topics, themes, not everything have a title) and a page number.

I often browse my notes even when I'm not looking for anything. I read what I've been thinking previously because that often sparks new ideas and thoughts.

One thing where I find pen and paper superior to digital is that it's easy to write in the margins, draw arrows and annotate. When I got my first iPad and tested out digital notebook tools (with stylus), I was excited about the idea that I can resize and move my existing drawings around.

Then it took me a few days to notice that I don't really ever need that. I don't need my "finished" notes to look tidy or good. I got over the need to have organised and structured notebooks and embraced the chaos.

I guess it's different things for different people. For me, the flexibility of paper is superior to any digital solution because it has the shortest "input lag" or "feedback loop" to my brain. I'm happy to sacrifice other potential benefits for that.

OP here.

> It's slow to write

Only to an extent. I write fast enough with pen and paper that my thinking is the bottleneck — which isn't really that fast. I don't need to write down everything I think so it also acts as a filter and processor of those thoughts.

> insanely slow to search what you've written

Compared to digital notes system, sure. But the way I use my notes, I don't usually need a full-text search to find stuff. I remember what I've been working on, I often browse through my notebooks to revisit ideas and most often these notebook notes are kind of a "working copy" where the search relevance is often just for the feature so it only needs to be fast to search for a few days or weeks.

I also do copy many of my notes down in digital format too when there's something worth capturing for long term storage for the sake of searching for example.

> almost impossible to copy or share

100%. Sharing is not a consideration for me, these are my raw pure thoughts and explorations, they don't often make much sense to other people as-is. Sometimes I may take a photo of a UI sketch or something to share if needed but otherwise when I have something to share, I write it based on my notes rather than sharing my notes as they are.

OP here. Last time my blog caught attention in HN, I was told I'm "living in a fantasy" and this time it's "pure romanticism".

The tools you shared are of course important and I enjoy having them a lot. Wouldn't want to work as a developer without version control or debuggers, for sure. Those are tools that if I lost them, it surely would slow me down and be annoying.

I do truly consider notebook more important to me than those. Writing and running code is the tool to get things done but software development to me is more importantly building something valuable that solves problems or makes life easier. And to that, code is often somewhat trivial implementation detail — it's much more important to figure out what to build and how.

Some people are good at thinking when they are in a code editor or other digital tools. My brain goes into detail implementation mode and it's hard for me to see the big picture when I'm writing in code editor and building functionality.

For me, it's crucial part of my job to take my notebook and use it as a tool for thinking before (and during!) coding. While losing access to the other tools would definitely slow me down, not being able to think through writing with pen and paper would cripple my thinking, my problem solving ability, my creativity and thus cause me writing bad software.

That's where the heavy pruning comes in. If there's too much coming in, it's important to get rid of the ones that are less important or most often skipped.

For me, the serendipity comes through discoveries inside the blog posts: people linking to other interesting blogs.

For me, RSS is the solution to FOMO because I don't need to worry about missing new posts because some algorithm decided not to show them to me or because I didn't happen to see them during the short window they were visible in other feeds.

My comment above about living in a fantasy was a reply to the root comment's notion that reading through RSS feed in the morning is a romantized, unachievable fantasy similar to a dad starting a day reading the newspaper (which is also not much of a fantasy as my dad has done that for decades).

So the morning routine I shared in the blog is the reality for me so I'm living that fantasy.

I wrote about many of those reasons in the blog post.

Cutting off the middle-man, slowing down the hectic life and staying in touch with my internet friends are a few of those reasons.

> it unavoidably leads to content that is created purposely to game that algorithm, which ultimately corrupts the user experience.

This is the functionality that really drove me away from social platforms, other than Mastodon. I prefer human curation over automatic recommendations for a couple of reasons:

1) Human curation creates less suggestions which makes it more manageable to go through

2) If I trust the source of the recommendation and know what they like, I can adjust my trust in the recommendation itself

3) A friend telling me something they enjoy is not motivated by money

> Being in charge of your own feed does not mean it will remain lean and sweet.

You're right. It does not automatically mean it. You have to maintain it just like anything else in life.

> is mostly just a fantasy.

It's a fantasy I live in daily.

> What happens in reality is that you more or less quickly ammass a big list of blogs and sources that gets updated by the hour

I guess this mostly depends on what kind of things you subscribe to. 95% of my sources are personal blogs of software developers or artists and most of them blog weekly or more rarely.

I couldn't handle a feed where sources update multiple times a day, it would just become a pain.

I really like that approach: provide an opt-in for people who need or want the extra features that require login (for example, cloud sync or saving history in cloud or whatever).

I'm always interested in checking out new tools. That's how I noticed Warp in the first place if it wasn't for the account requirement, I would have given it a go to see if it would have improved my workflow compared to what I currently use (iTerm).

I never got as far as figuring out if it would be that because the requirement for account stopped me on my tracks at the very beginning.

In my experience, print statements should be the starting point because they offer a fast and easy solution and can help you first of all confirm that you're looking at the right part of the code.

One point when I switch from print to debugger is when I need to run the thing over and over again switching print statements on the way – at that point it makes sense to bring in a debugger tool, halt the execution and explore what's wrong.

I haven't used LaTeX enough to really have an answer, sorry. Hopefully someone else who's a power user can comment!

I love this idea. As someone currently living in Helsinki but having been an expat before, having support in finding the way at the beginning is so valuable.

I hope this will evolve into a one-stop shop at finding information about paperwork, apartments, bank/phone/utilities etc that are always different in every country and lots of work to be figured out.

If there's a city-provided service that reduces stress on that level, it would be super attractive to me.

This is such a great initiative.

I work as a dev at Futurice and I've been enjoying the opportunity to the fullest. I would be tinkering with stuff and releasing my projects as open source regardless so it's such a great perk to get little extra cash for that as well.

> However, writing good documentation can be really hard. As the developer, you are, at the same time, the best and worst placed person to document. Best because you know exactly how the software is supposed to work, and worst, because you might miss documenting things that seems obvious to you, but not to the user.

This is an important point! That's why I think it's so valuable to constantly have discussions with the users of your products. Not only to improve the products themselves but the documentation and the on-boarding process.

I totally agree with you. It requires good understanding of the project but also it's beneficial to know the pitfalls and decisions made or left unmade that ended up shaping the project. That's why I encourage developers to make documenting (just like testing) a part of feature development and bug fixing rather than an additional hurdle.

I like Tom Preston-Werner's Readme Driven Development[0] approach. Instead of leaving documentation as something that happens as an afterthought, start with it. I've tried it a few times with my smaller hobby projects and it has helped me a lot.

Similar to TDD, RDD allows me to design the API before I ever write the actual code. I also get to design the build process, contribution model and bunch of other things up front.

When it comes to the "why" of projects, I like DHH's Doctrine document[1] on Ruby on Rails. I wish more software projects would feature a similar document since that answers a lot of questions, especially about the opinionated decisions.

[0] http://tom.preston-werner.com/2010/08/23/readme-driven-devel... [1] https://rubyonrails.org/doctrine/

Have you talked with people using your tools and asked them? Unfortunately people will rarely send unsolicited good feedback to tools they enjoy so it's important to chat with your users.

Hey! Original author here, excited to see open source documentation brought up in Hacker News.

I feel like documentation in general is a topic we developers don't talk about enough and it's often cast aside as a "we'll do it if there's time" and I think we all know there's never gonna be "time".

If you wanna set up similar things with your colleagues or local community, feel free to hit me up (email in bio) or ask here and I'm more than happy to share ideas and how we made it happen.