|
|
|
|
|
|
by alpaca128
1920 days ago
|
|
|
Better documentation. And with better I mean documentation that does not rely on as many assumptions about the reader, and docs that include enough examples. I don't care about that one example which only covers the most trivial use-case that you included so there's an example in the docs. Examples should be like unit tests, I don't want to play the archeologist and dig through pages of outdated info just to figure out how to set that one weird flag. One example for docs I enjoy is the reference for the Rust standard library. It still could use a few more examples here and there but overall it's among the best I know, together with tailwindCSS' website which is also great. Don't be like the devs of that one JS animation library which locked further examples behind the registration form for another web platform, failing to mention those hidden examples are more or less a copy-pasted variation with slightly different numbers. And I haven't thought about it very deeply yet but I'd like a tool or maybe lightweight processing language that lets me quickly visualise debug output and similar data. Often it feels like the main time sink at chasing certain bugs is how I either have to look at the raw data and numbers and try to see a pattern, or more or less start a whole side project to properly process and visualise it.
Possibly I'm just missing something obvious or overlooked the usefulness of a neat tool at first glance. |
|
|
Just a recent example (it's just AN example, there are probably way better examples than this one): I started recently to code a website after years without putting my hands in web development.
I went through some documentations of multiple lightweight frameworks for server side coding:
100% relies on the reader to know how to use the latest fancy-cool-kids-choice packet manager for the given language. If you do know by heart your brew-npm-composer-pacman-I-dont-know-what, good for you dear documentation writer -> not everybody does!! Which means that if, for some reasons, there is the slightest issue with any of the versions of the hundreds of dependencies your "basic application" requires, it means that the newcomer for your framework must found his.her way into a stack of tools and dependencies that is galactic in size.
More than half of the documentation said that if you don't want to use the packet manager you can use a virtual machine or a container manager (Docker)
100% of the documentation I read started showing code to configure the project WITHOUT mentioning in WHICH files the code should go into -> it was implied!!! -> searching about the topic online made me realize I was not the only one, and the response from the helpers were actually very efficient and correct and were not part of the documentation!
100% of the documentation included non-self sufficient information to have something working and running -> proof is, search for one the problems on whatever search engine -> led to hundreds if not thousands of results of people asking their ways into having the "Getting Started tutorial" to actually work!!!