News for hackers. Stuff that matters.
Re:Will Bun JavaScript Take Node's Crown by simonw on Sunday August 14, 2022 @08:13AM (#32458604)
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!

Re:Will Bun JavaScript Take Node's Crown by beebeepka on Sunday August 14, 2022 @09:14AM (#32458986)
Good 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

Re:Will Bun JavaScript Take Node's Crown by simonw on Tuesday August 16, 2022 @04:35PM (#32488538)
The two largest projects that I write documentation for are https://docs.datasette.io/ and 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!

Re:Will Bun JavaScript Take Node's Crown by gervwyk on Sunday August 14, 2022 @08:17AM (#32458629)
This is good advice, thanks. Really want to practice my writing more as well.