@rperezrosario@mastodon.social8 Light writer Taylor Keazirian argues in favor of maintaining a set of "living" documents as part of software development project efforts. Common misconceptions about software documentation are addressed and refuted with insights on what a minimal technical set of documents for a software project should look like.
"Mastering Technical Documentation"
@castarco@hachyderm.iorant on software dev practices
What is it with P5js and virtually all its ecosystem (like Q5js) that, still today, didn't manage to _properly_ package their libraries to be distributed and used via package managers?
Same with their insistence to push global resources and state everywhere... and of course virtually not documenting any of the truly delicate details, just the trivial stuff that could be auto-discovered by relying on auto-complete tools.
I kind of understand wanting to keep the vanilla experience alive, making it "easy" for novices... but that shouldn't be at odds with more "professionalized" production pipelines, at least *not that much*.
For example, with Q5js:
- The NPM packages could be mentioned in their documentation (they are not, even though they are official)
- The NPM packages could define proper exports (same for the JS modules themselves), not forcing us to rely on relative paths to files in node_modules... 🤦
- Globals could be at least namespaced... of course, it would be much, much better if they didn't exist at all.
I'm writing this in 2025, not 1993... and I'm... "triggered".
At this point I'll have to check if I have any other neuro-condition beyond ADHD that makes me "obsessed" with technical flaws, because it seems to be a "me problem" when either virtually nobody sees that as a huge collection of fatal design flaws... or they see it and don't care at all.
