Some interesting stats for some of you: The ratio of git commit types[1] in #ThingUmbrella over the past 6+ years (1st colum) vs over the past year only (since 2023-01-01, 2nd column):
These numbers show a drastic uptick in documentation related efforts (1.6x more commits of that type) and I sincerely hope this effort will start bearing fruits at some point and wasn't all wasted...
Underlining this increased focus on documentation & explanations is also visible in terms of effort creating/refactoring/maintaining the 155 example projects included in the repo. Here're the numbers of example related commits over the past three years:
2021: 84
2022: 80
2023: 170
Personally, I don't know of any other project which supplies this amount & variety of examples (from basic to more advanced and not even counting the other hundreds of code snippets in doc strings showing basic usage & use cases) - yet documentation remains the #2 issue deemed "problematic" (after "discoverability")...
I'm not sure if my neurodivergence is at play here, but I just don't understand how to connect some of these efforts & findings (or I don't understand people's expectations, also not helped by lack of concrete feedback given, even if asked directly)...
[1] Being able to easily build additional tooling/automation is one of the many amazing side effects of using https://www.conventionalcommits.org/ — I highly recommend it for your own repos!
@toxi would be interesting to know more about the neurodiversity. Is it diagnosed?
Often surprised how many good coders do not fit the usual spectrum. I.e. @acegikmo
@toxi My main criticism of the API docs is that parameter descriptions are often missing. They are in the source code, but they apparently get lost when the docs are generated. E.g. math/clamp().
Add comment