Being a founder is one of those roles where you're giving feedback on basically everything, while also trying to get a couple of things done each day on your own. Two weeks ago, I was working on a really hairy problem with @maestromac. We were making slow but steady progress, and learning a lot together. It was one of those problems where it'd take you 30 minutes each time to re-orient yourself to what you were dealing with, and what new solution you were trying out. It was, and is, a real doozy.
But then! A few days into it, a totally administrative/business/non-technical problem came flying my way. It was something that needed my full attention, so I dropped everything else I was working on. That took away several days and now it's been over a week since I coded. Each time I take a break from coding, I feel like I've taken many steps backwards and it's hard to get back into the headspace. This time in particular, I dreaded facing this relentless problem.
I really didn't want another coding-dry-spell week to fly by, so to get back in the groove, I've decided to update some documentation instead. I find that the magic of pushing something straightforward and seeing it pass all the tests and make its way to production, is the small win that I need to feel inspired again.
I'm only now realizing that documentation, or updating copy, or fixing a teeny tiny bug is almost always what I need to do for smoother context switching. I think this will help me drag my feet less 😅
Top comments (10)
I love writing documentation, not just from an API point of view. I'm given a lot of leeway as to how I implement the back-end UI for things and I try to keep screenshots and tutorials up to date for CMS administrators and so forth.
A couple of jobs ago I worked with someone who was, like, a professional technical writer, and that experience has made me push for my bosses to employ TWs everywhere I've worked. Haven't made much headway, but I keep trying.
Most developers hate writing documentation as far as I can see on projects I've managed in big corps mostly because it's a daunting process and it takes too much time to maintain (I mean true doc not just useless comments) so I'm working on a format and above all tooling to ease this for all programming languages - there are already javadoc for java for example but it will be a layer above.
It's far from being there because I have a lot of other stuffs, at the moment there is a core format here readable.red - that I have to better document I know :)
Documentation is a great way to contribute to open source too. If you use something a lot and are a little scared of opening a PR with code, writing or updating docs are usually always appreciated and have a high impact on the people who read the docs.
This is exactly what I have been doing. Sometimes it's little things like nitpicky syntax, accuracy or wording.
Works for me too - I find that summarising what I've done so far in a problem area helps me get a better view and gets me back into the challenge, whilst also helping with the big red bus/lottery win scenario!
Technical docs and end user documentation helps me see in different contexts and points of view which provide more data or thoughts.
For me to solve issues I'm usually writing sometimes in a journal like style to break down the issue so I might be able to see a trend in though and I usually write why a few times and try to solve the why. The why sometimes points me in the direction to solve it within its context without going crazy (sometimes only a little crazy). Sometimes the why leads me to more questions to solve.
I've been handed bugs that seemed random but managed to get them to replicate and for that I had to write trends and hypothesis and tested these. Sometimes this can be found in a teaching style of documentation -- almost textbook style as opposed to very short. More like guides.
These methods of writing all help my ability to code. I'm not your more elegant coder but sometimes I'm fairly non-linear in the style.
How do you write your docs?
Do you people include failed attempts, considerations and whies in your documentation? The process things you tried first before eventually deciding to implement it as it is. Things that failed.
My documentation is always strictly technical / api reference-like while others write a novel about the journey.
I do rather enjoy writing documentation...except for the year I spent working on virtually nothing else.
😅
Totally! It's like stretching before a run - getting back in the workflow groove first before digging into the code.