I have two kinds of people I mentally target when I write documentation: a 6 year old child with an abnormally long attention span, and a grumpy, rude 60 year-old mechanical engineer who isn't quite old enough at the time to skate to retirement before having to learn the thing I'm documenting.

Writing for a child forces me to keep the words and concepts very, very simple, and to write in a style that builds up usage of the program from first principles. Writing for the grumpy old-timer is a practice in minimizing questions from them, forcing me to do a sort of final pass on the overall design of what I'm writing about, to defend design choices, and to add future improvements to the backlog. Drafting the documentation for semi-finished features that are still in progress has sometimes led me to change the design in order to make writing the docs targeting these two people simpler.

lol. that's me; only I start by writing out the problem as an email to ask someone for help. 90% of the time, I find that I didn't have a complete understanding of the problem to begin with, and I usually end up solving it before hitting "send".

Then I'll have this odd memory of - "I discussed this with you, I told you all abo- oh wait, I didn't send it."

I thought I was the weird one... Many a times have I debugged an issue and was convinced of where is the bug and what the fix is. Only to discover that I was off in both the regards when I sat down to write a detailed email to the team!

I felt I was wasting too much time. But I've realized that for me the time spent writing something in details has always helped me fill in the gaps and also discover the unknowns.

I found that sometimes sending it is required for me when I‘m absolutely stuck and have explained it a few times. It sort of commits it to memory and frees up mental resources then able to come from a different direction.

Yes. Very often the email never gets sent — because I find the solution while writing it.

This is an incredibly common experience, lots of people I've asked do this.

When writing a StackExchange post asking for help, I want to include all relevant information and include a list of things I've tried, along with explanations for why they're dead ends.

Writing it all down sometimes helps me realise that one of the ends is in fact not dead.

This happens more often than I'd like to admit. More often it's on work chat or a call, but the principle holds: I try to explain my problem to someone else and while deepening the explanation, I get a face-palm moment (the answer was there all along!), thank the person for its time and franticly start working on the solution.

Rubber ducking can be a highly productive measure when your mentally clouded and can take many forms.

I do the same by walking and mostly talking to myself like a mad scientist.

I'm pretty sure my dog would qualify for an entry level engineering position at an FAANG from listening to me talk about work while we're walking.

I'm often found in the back lot, walking around and yelling/gesturing to no one at all about the problem I am trying to solve.

Jonathan Blow mentioned in one of his interview that sometimes solutions would pop up when he was in middle of dance class or yoga class.

I resolve a lot of bug tracker issues (before actually opening them) that way.

I started note taking in markdown. I used to note take a lot on paper and it always became a mess.

I'm using Obsidian right now for this, although you can just use plain code editor it's nice to have WYSIWYG.

I've just started using obsidian, but only for a subset of my work, to work on individual documents with a very rigid structure. Do you have any tips on taking obsidian to the next level, using it as an integrated tool rather than just a one-off editor?