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 e

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