Hi, quick post. I guess this is considered a feature request.
I’ve noticed I often end up a bit confused while looking at documentation by the lack of images (or examples). This isn’t a problem for common classes where there are tutorials, but there’s a lot of classes that go a little under-documented, where things aren’t clear because there are no images. And the time spent implementing in practice just to see that it’s not quite the feature you were looking for could be saved by having a simple example image.
What do people think?
I also think it could be cool to be able to contribute to the documentation, like I said, for the sake of the more obscure classes. And maybe be a little clearer on the classes that, in the forum, are found to be under the “which Jules intends to deprecate” category.
(But don’t get me wrong. I’m in love with JUCE. I just hope I can contribute to making it better!)
Coming from developing on Qt, I think their documentation is one to take inspiration from. Their pages are similar to JUCE’s but in addition, have examples, images, best practices outlined. Here’s an example: QPushButton documentation.
They also have documentation pages on whole structures, like the Signals and Slots feature. The
Component structure and the
ValueTree structure come as examples of pages that could have a hefty page of documentation, with examples, outlining the best practices, and the different classes that can be used in conjunction.
JUCE, I found, is relatively super easy to get into. But there’s big blocks in certain areas in terms of comprehension of why things are the way they are, and how exactly to implement stuff, especially for beginners. And on some topics, like garbage collection and smart pointers, I’ve just been unable to really get the best practices in my head, and it leaves me feeling basically worse off then not trying to implement them at all.
I don’t know about images, but small code snippets to show how certain classes/functions would typically be used would be immensely helpful. Although you could say, just go look at the example projects…but sometimes knowing which project might have a particular GUI widget etc that you want to use is not obvious and short examples (or at least - suggestions as to which demo project an example could be found in) would have saved me a lot of time learning to use JUCE. E.g. on CplusPlus.com (a random example) https://www.cplusplus.com/reference/array/array/begin/
(Qt doc looks good too)
All true. Examples are essential for getting a grip of the ideas. The tutorials provide the material for the most part, but there’s two issues with them being the only source of examples: Classes don’t link directly to tutorials, and tutorials are more bloat if we want to cover everything. Similar to what you hit upon.
But images could be useful as well. I get that the look and feel and all that varies for each implementation, but the tutorials have images in them precisely for the reason I think the docs should have them too.