5 ms·
I've learned over time that it's much easier to incrementally update existing docs than it is to add them to a large project from scratch - so every single one
by simonw 4y ago
I've learned over time that it's much easier to incrementally update existing docs than it is to add them to a large project from scratch - so every single one of my projects, no matter how small, now has documentation from day one.
As I add new features I update the docs to reflect the changes, trying to keep those documentation updates in the same commit as the tests and implementation.
Since I started doing this the quality of documentation I produce has gone up a ton, because I'm constantly exercising those muscles.
It's been a huge win for my coding quality and productivity too - I don't have to remember as much stuff because I can refer back to the docs, and documenting as I go along causes me to make much better design decisions.
Worth noting: I'm a native English speaker writing documentation in English, and I've been blogging frequently and writing online for over twenty years so I've accumulated a LOT of writing experience. So what's easy for me may not be easy for other people!
- gervwyk 4y agoThis is good advice, thanks. Really want to practice my writing more as well.
- beebeepka 4y agoGood point but writing and maintaining README.md files for your solo projects is nothing like writing proper docs for big projects with multiple contributors and users. That's a full time job, isn't it? Writing non-code is easy and fun to me - I used to do it for a living - but when I am pressed to deliver features, documentation takes a backseat. Also, I've never felt like documenting other people's code
- simonw 4y agoThe two largest projects that I write documentation for are https://docs.datasette.io/ https://docs.datasette.io/ and https://sqlite-utils.datasette.io/ https://sqlite-utils.datasette.io/ - they're both big projects with multiple contributors, though most of the commits are still from me. I find the same approach I take to READMEs for smaller projects scales up pretty well: any time I make a change to one of my larger projects I ensure that the documentation is updated as part of that change. If I accept a PR from someone without documentation I'll follow up by adding the docs for it myself in the next commit. I think that's more reasonable than demanding people add documentation if it's not necessarily their core skill set. Honestly, I'd love to experience working with a professional technical writer on this kind of thing, but that's not something that's happened at any point in my career to date!