Been thinking again about recent #ThingUmbrella survey results and also what @inthehands emphasized recently, i.e. that "Software development is an intensely social discipline.". I fully agree.
Too much power in a programming language/tooling means no or very few struggles. On the other hand, very few struggles also mean very little incentives for community to form/grow, to exchange, to debate, to contribute... (basically also one of the more indirect morals of The Lisp Curse)
60-80% of the survey feedback (finaly comments) are along the lines of "thi.ng is amazing", "thi.ng has been a huge inspiration", "a real treasure trove", "love the project", "thi.ng is awesome and a joy to work with"... Hearing this makes my heart jump for joy!
Yet, I'm also keenly aware there are aspects of these projects which cause people to "struggle", and I'm also constantly working on improving the DX & docs for everyone, including creating new custom tooling and automation...
Today, I spent most of my time on new tooling to extract the almost 800 code examples embedded in API docs to individual source files, in order to run/try them directly from the command line... With the vast scope of the larger project, this means each time there's a new update/tool like this, there're 100s (sometimes 1000+) of source files to check, to edit and verify, mostly manually (today I managed write the tool, but only updated a few dozen source files...)
I'm often feeling the effort & time spent on these tasks is becoming harder to justify, if there's so little feedback for all the documentation materials which are actually there. The mostly vague complaints about docs missing, being confusing or difficult topics are not really helpful to improving these aspects. I also can't help but wonder why there's been so very, very little offers to help with that (if people have issues, the least is to be constructive about it...)
How do other OSS project maintainers deal with this? Has this ever been an issue for you? Apart from investing even more time in these things, what else can I do? The 150+ example projects don't seem to help either... Part of this discussion feels like catch-22...
@toxi@inthehands Personally, I really appreciate the documentation, and when that isn’t enough (I can think of a couple of undocumented functions that you’re now making me realize I should have submitted docs for 😅) I jump into the code.
One thing that I encountered early on was that some examples use other libs, requiring a broader grasp. I like it now, but it can make getting started a bit intimidating. Your blog posts were the best for this!
Add comment