Hope I don't come across as too critical. I totally get it and sympathize since I've recently been through a challenging documentation project that has very similar catch-22s. It's super frustrating that people want a simple story and have no patience for nuance, but that's how it is. Koliber's sibling advice is very practical and would be my tl;dr on this probably but to expand a bit.
There are basically about 5 different kinds of things you can build: tools/apps, libraries, frameworks, services, languages. I'll hazard a guess that most engineers are used to slicing stuff up this way and that much confusion results from arranging docs in terms of case-studies, which is maybe more appealing to management and/or academics? From the perspective of engineers.. "use cases" are expected to be presented as a small bulleted list or similar. Paragraphs are a losing proposition here, because if they want more, then they are ready for a really concrete and runnable tutorial, and almost anything in between will annoy them.
In terms of docs, it's very tempting for inventors but almost always a mistake to add "paradigm" to the main 5, even if it's true. Academics want that up front, but for industry where results beat methodology, paradigms are a "show but don't tell" thing that you have to lead people into very slowly if you even need to address it directly at all. You can break that rule at your peril and capture interest from a few hardcore alpha nerds.. but even then it is best in the context of a well-designed and otherwise practical tutorial in a optional "post-mortem" section dedicated to recap/discussion. Don't mix it with the main tutorial, and always be as ruthless as possible about separating philosophy and pragma. (I see you're on the way, and there's already a separate domain.)
Building stuff that's in several of the 5 categories at once is often the most productive work and by far the most fun, but also the hardest to present. You can't show more than 1 aspect of the big 5 at once, or you risk losing people. And you always have to be really clear about which one you're presenting for consideration. If you can lay things out like that and then cross-reference docs between the tool/language/framework aspects, it enriches the content and makes it feel comprehensive and complete. More importantly though: it gives people that are in the wrong spot some ability to course correct and that reduces frustration that would otherwise make them complain/turn away.
Books and videos are probably for people who are already true believers. Unfortunately getting more people into that category faster actually means making them say "wow!" in ~15 seconds. That's enough time for a 1-liner, a 15 line program, or a gif. Sad but true. The book's mentions python, d3, tons of popular stuff that is a good hook.. but most people probably don't click in, and if they do the level of detail/runnability doesn't feel quite right. I suggest polishing like 3 of those and lifting them to the main page, maybe also involving docker to make a quicker quick-start.
HTH. Explainability and debugging generally are both about to get a LOT more important for obvious reasons the way things are going. And documenting cool stuff is way harder than building it sometimes ;) I'm thinking a lot about how to do these things myself so I'd really welcome drive-by feedback from anyone else if my assumptions about "average impatient engineer" are way off base here.
Thank you very much. This is an extremely useful input.
Would you by any chance be interested to get a tour from me? At the very least you'd get to see what it is, and perhaps in the process you might find ways to explain it.
If you are up for it, please connect with me in some way (the GT Discord, @girba on LinkedIn, @girba on X, @tudorgirba.com on Bluesky) and we'll take it from there.
There are basically about 5 different kinds of things you can build: tools/apps, libraries, frameworks, services, languages. I'll hazard a guess that most engineers are used to slicing stuff up this way and that much confusion results from arranging docs in terms of case-studies, which is maybe more appealing to management and/or academics? From the perspective of engineers.. "use cases" are expected to be presented as a small bulleted list or similar. Paragraphs are a losing proposition here, because if they want more, then they are ready for a really concrete and runnable tutorial, and almost anything in between will annoy them.
In terms of docs, it's very tempting for inventors but almost always a mistake to add "paradigm" to the main 5, even if it's true. Academics want that up front, but for industry where results beat methodology, paradigms are a "show but don't tell" thing that you have to lead people into very slowly if you even need to address it directly at all. You can break that rule at your peril and capture interest from a few hardcore alpha nerds.. but even then it is best in the context of a well-designed and otherwise practical tutorial in a optional "post-mortem" section dedicated to recap/discussion. Don't mix it with the main tutorial, and always be as ruthless as possible about separating philosophy and pragma. (I see you're on the way, and there's already a separate domain.)
Building stuff that's in several of the 5 categories at once is often the most productive work and by far the most fun, but also the hardest to present. You can't show more than 1 aspect of the big 5 at once, or you risk losing people. And you always have to be really clear about which one you're presenting for consideration. If you can lay things out like that and then cross-reference docs between the tool/language/framework aspects, it enriches the content and makes it feel comprehensive and complete. More importantly though: it gives people that are in the wrong spot some ability to course correct and that reduces frustration that would otherwise make them complain/turn away.
Books and videos are probably for people who are already true believers. Unfortunately getting more people into that category faster actually means making them say "wow!" in ~15 seconds. That's enough time for a 1-liner, a 15 line program, or a gif. Sad but true. The book's mentions python, d3, tons of popular stuff that is a good hook.. but most people probably don't click in, and if they do the level of detail/runnability doesn't feel quite right. I suggest polishing like 3 of those and lifting them to the main page, maybe also involving docker to make a quicker quick-start.
HTH. Explainability and debugging generally are both about to get a LOT more important for obvious reasons the way things are going. And documenting cool stuff is way harder than building it sometimes ;) I'm thinking a lot about how to do these things myself so I'd really welcome drive-by feedback from anyone else if my assumptions about "average impatient engineer" are way off base here.