4 ms·

Because being a small project with limited resources requires devs be as resource efficient as possible. Docs, demos, tuts are all super important but it create

Because being a small project with limited resources requires devs be as resource efficient as possible. Docs, demos, tuts are all super important but it creates an additional maintenance overhead - if they are not maintained up to date, they become worthless. So for the early stages of a project it makes sense to keep the overhead low and work with a small group of focussed early adopters. As projects grow, mature and become more stable, more investment into learning material becomes important. Doing it too early burns valuable resources.

chiefalchemist 4y ago
> As projects grow... I'd argue if should replace as. The point being docs are all but essential for growth (and added participation). To neglect them is self-defeating. Put another way: Docs are an investment. They have a known return. Again, we've seen this. We know this. Yet again and again there's case after case of docs denial.
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 ago
  This is good advice, thanks. Really want to practice my writing more as well.
- beebeepka 4y ago
  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
  - simonw 4y ago
    The 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!
rikroots 4y ago
I've been working on my OS library for 9 years now, almost entirely by myself. For the majority of that time I kept documentation separate from code. Now I do enjoy documenting stuff - I have diplomas in both Computing, and Creative Writing - but my various approaches to documenting the project would start off with the best intentions but soon enough degenerate into an irrelevant mess as I tweaked code, forgot to update related webpages and demos, etc. In 2017 I stopped working on the project entirely: I'd coded up a new major version of the library but never released it because knowing I had to overhaul and re-document so many different pages, demos, etc ... like a dementor, it sucked all joy from me. Then in 2019 I recoded the entire project from scratch. This time I thought about the documentation first, before I wrote a line of code. I decided the best approach was to generate the main documentation from inline comments. I did this for both core code, and for demo examples - the demos stopped being standalone afterthoughts and became instead my end-to-end testing suite. To present the documentation to any developers who might show an interest in the library, I coded up the library's website in a way so that the core documentation[1] and the demos[2], with easily accessible code, could be very easily copied over to the website whenever I rebuilt the library (which regenerates all the documentation). I also added a set of lessons to the website, and a set of "How do I" articles - both of which are an ongoing project. The library's website doesn't have any functionality where users can ask questions - but that's what the GitHub issues and discussions pages[3] are for. The system isn't anywhere near perfect (I still need to automate the demo testing, for example, and there's no CI for copying stuff from the repo over to the website, etc) - but, given the depressing messes I've managed to fall into in the past ... it's working really well for me! [1] - https://scrawl-v8.rikweb.org.uk/documentation/ https://scrawl-v8.rikweb.org.uk/documentation/ [2] - https://scrawl-v8.rikweb.org.uk/demonstrations/ https://scrawl-v8.rikweb.org.uk/demonstrations/ [3] - https://github.com/KaliedaRik/Scrawl-canvas https://github.com/KaliedaRik/Scrawl-canvas

chiefalchemist 4y ago

> As projects grow... I'd argue if should replace as. The point being docs are all but essential for growth (and added participation). To neglect them is self-defeating. Put another way: Docs are an investment. They have a known return. Again, we've seen this. We know this. Yet again and again there's case after case of docs denial.

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 ago
This is good advice, thanks. Really want to practice my writing more as well.
beebeepka 4y ago
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
- simonw 4y ago
  The 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!

rikroots 4y ago

I've been working on my OS library for 9 years now, almost entirely by myself. For the majority of that time I kept documentation separate from code. Now I do enjoy documenting stuff - I have diplomas in both Computing, and Creative Writing - but my various approaches to documenting the project would start off with the best intentions but soon enough degenerate into an irrelevant mess as I tweaked code, forgot to update related webpages and demos, etc. In 2017 I stopped working on the project entirely: I'd coded up a new major version of the library but never released it because knowing I had to overhaul and re-document so many different pages, demos, etc ... like a dementor, it sucked all joy from me. Then in 2019 I recoded the entire project from scratch. This time I thought about the documentation first, before I wrote a line of code. I decided the best approach was to generate the main documentation from inline comments. I did this for both core code, and for demo examples - the demos stopped being standalone afterthoughts and became instead my end-to-end testing suite. To present the documentation to any developers who might show an interest in the library, I coded up the library's website in a way so that the core documentation[1] and the demos[2], with easily accessible code, could be very easily copied over to the website whenever I rebuilt the library (which regenerates all the documentation). I also added a set of lessons to the website, and a set of "How do I" articles - both of which are an ongoing project. The library's website doesn't have any functionality where users can ask questions - but that's what the GitHub issues and discussions pages[3] are for. The system isn't anywhere near perfect (I still need to automate the demo testing, for example, and there's no CI for copying stuff from the repo over to the website, etc) - but, given the depressing messes I've managed to fall into in the past ... it's working really well for me! [1] - https://scrawl-v8.rikweb.org.uk/documentation/ https://scrawl-v8.rikweb.org.uk/documentation/ [2] - https://scrawl-v8.rikweb.org.uk/demonstrations/ https://scrawl-v8.rikweb.org.uk/demonstrations/ [3] - https://github.com/KaliedaRik/Scrawl-canvas https://github.com/KaliedaRik/Scrawl-canvas