Website: Simple example on each class doc page

Feature Requests
1

I would think it is in the interest of the JUCE team to get beginners going as fast as possible, so they can convert, program that is, their ideas into a product.

Some who start out with JUCE, myself included, should perhaps have had a bit more experience with C++ before they begin with JUCE, but hey it can be hard to wait when you have a great idea :slight_smile:

Anyways struggling with my first JUCE app, which was originally intended to be a revolutionary synthesizer, and I mean revolutionary, as I am so old I have experienced synths from the 70ā€™s up until now, including several hundred software synths, to know I may have something new to add, anyways I realize that I have quite some way to go before I can begin programming a synth with JUCE, so I started with an arcade style game.

But I am still struggling, and yes I know had my knowledge of C++ been much better I would probably not have. It is not that I do not have programming experience. I programmed for the Digital PDP-11, the ABC-80, the Commodore 64 and VIC-20, Spectrum, and many more back in the early 80ā€™s, including assembly language, Basic, Pascal, and C, and a few years ago I published a 10K+ lines of JAVA code Android finger drawing App with still to this date unique features, and of which I made $35K with the first year after became top 50 on Amazon.

Ok back to topic, when searching the net and mostly this forum for possible answers, I see the same questions asked over and over again, and for questions and answers that are a bit older, some who answered kept referring to the JUCE Demo. Two thing I get out of that. 1) It seems to me that more example are needed to get beginners going as fast as possible. 2) It seems some of the examples from the ā€œoldā€ before JUCE 5.3, needs to be put back for public viewing, perhaps reworked if needed. Anyways here is my main suggestion to the JUCE team.

You are docs are really good, but they would be SO MUCH better, if you would add a simple example on each ā€œClass Referenceā€ doc page.

2

The Juce Demo is now called the ā€œDemo Runnerā€ and as far as I know, still has all the classic Juce demos included.

3

If I find the docs lacking some detail I am looking for, I often search the Demo and other extras, for the API I am interested in.

4

I looked through all of them, and some examples of classes that are referred to in a bit older forum answers seems gone, and I have specifically used greb in vain to search for a keyword referred to from this forum.

5

Now, Iā€™m not attacking the idea. I would simply like to understand what the proposed class examples provide over the ā€œDemo Runnerā€ itself, let alone the tutorials? The latter is fairly well done, and contains a large set of practical examples. The Demo Runner is more of an aggregate of features and tests, but with everything being PIP driven it should be fairly straightforward to pluck particular functionality to play with it and analyse it more closely.

Are these two things lacking? What can be improved on those avenues to make the barrier of entry lower?

And also - with JUCEā€™s code being entirely open and accessible, this should make the venture into using the framework much easier. (ie: a quick ā€œCMD/CTRL + Fā€ to attempt finding functions calls or class instances.)

6

One may have to be a beginner to understand the power a few lines of actual working example code can do at the top of each doc page.

Sure the examples are good and so are the code in the Demo Runner, but perhaps it would have been better to make them consistent, as some only contain one header file, and a few others are split up. But still they do not contain examples of all classes, and I think that would be a huge boost to beginners like me.

7

I donā€™t think itā€™s entirely reasonable to have a beginner suddenly understand all of the concepts; how they can (and at times, how they shouldnā€™t!) fit together takes, well, time and patience to understand themā€¦ and there are many, not even just within JUCE itself! There are so many abstractions and patterns atop the code itself.

It sounds worthwhile identifying what functionality should be better documented and/or demoed and/or be made into tutorials.

1 Like
8

Off course it not reasonable to have a beginner understand all concepts. I just wanted to understand what I needed, and I am saying a few lines of example code at the top of the doc pages I searched, for a particular class or function I needed, would, or should?, have helped me so much that I did not need to ask on the forum.

One can perhaps using some search code, to traverse the forum, and see what is asked the most.

9

Although these days I usually jump into the library code when I want to understand something better, as a beginner I know how useful it is to have simple working code examples for a given class. Even now, there are classes I come across whose usage is not obvious at first glance. I donā€™t think itā€™s an unreasonable request.

10

Agreed, but I think requiring each and every class to have a code example is too demanding, and redundant at times.

Several classes are either too trivial, in which case no code example is needed, or too complex, in which case a pointer to e.g. a tutorial, or the mention that one exists, would be a better choice IMHO.

Nonetheless, if there are specific classes that would make use of a reasonably small code example, I think that could be reported to the JUCE team for inclusion in the class doc

1 Like
11

I think the overwhelming majority of cases discussed here are due to a lack of use of the C++ language, not the framework itself. If the language is mastered, using the framework becomes much easier.

1 Like
12

I think you are absolutely right, however as Jules said in his keynote about Soul last year, most, including me, arenā€™t. What I am trying to point out here is that I think a brief example on top of the ā€œClass Referenceā€ pages, something that shows declaration, implementation, plus notes (i.e. hints as what to watch what out for/remember) could get people like me, and judging from the repetitive questions asked on this forum and elsewhere it seems there are quite a few, get going a lot faster and that must be, should be, part of the developerā€™s mission.

Or to put it another way, I have 37 years of programming experience with so many languages I lost count, but probably the least with C++. I am not sure I have another 37 years to really master C++, ok trying to be funny by exaggerating here, but my point is I want to do some exiting stuff with JUCE now and learn more about C++ along the way.

13

I understand such demand but personally I would not change the JUCE docs in this direction. They are what they are: just pure class index and IMHO itā€™s perfectly enough. I think more tutorials would help or better: JUCE matured to the point where somebody should write a big, professional book, a reference bible discussing all framework features and possibilities. But it would be a monumental task, requiring a lot of time and effortā€¦

14

I started to work with JUCE about three years ago and my C++ knowledge was at the level that I was able to master Arduino projects with a handful of source files, e.g. very basic. I didnā€™t even know there were namespacesā€¦

I can remember having probably the same questions back then as you have now, so I would say I can totally feel you. However, fast forward to today, I worked with C++ projects nearly every day since then, JUCE today feels like one of the easiest to understand and best documented C++ libraries out there ā€“ you will know what Iā€™m talking about as soon as you leave the JUCE-land and integrate some other libraries. As others pointed out too, I would say that this is mostly because I mastered the language itself. From my personal viewpoint, I would appreciate it more if the JUCE team spent its time adding features instead of adding lots of documentation. Probably a lot of paying JUCE users have a similar point of view. I donā€™t want to say that your request is wrong in any way, however I think itā€™s hard for the JUCE team to find the sweet spot here.

And I would like to encourage you learning C++ in the meantime as even if they decided to add something like that, the requested example code wonā€™t pop out suddenly. If you have so much programing experience, Iā€™m pretty sure it wonā€™t take 37 years until you feel really comfortable with this language!

Another thought, as there are really a lot of classes and there might not always be one ā€œrightā€ way to use them that could be put in a short example, would you mind sharing which classes or tasks seem the most difficult to you at the moment?

2 Likes
15

Exactly!

16

But it would be a monumental task, requiring a lot of time and effortā€¦

A few years ago a publisher contacted me about writing a JUCE book, and the calculus was simple ā€“ I could spend a year doing that on nights and weekends (there was an advance, but not a ā€˜quit your jobā€™ advance) and hope to earn out if a few hundred books sold, or spend those nights and weekends working on projects that can eventually payoff more significantly.

If I were starting with JUCE now and not already a pro-level C++ developer, the first place Iā€™d start would be Joshua Hodgeā€™s ever-growing set of tutorials on YouTube, then live inside the JUCE demos for a while.

After that: every minute spent studying the JUCE source will repay you over and over.

1 Like
17

I am here using JUCE, after briefly experiencing other platforms, because it seems the best at the moment. My request is not just for me, I think it can benefit every new person coming to JUCE, and I think the quicker they can get started, the sooner they will turn into paying users.

The problems that stumbled me, I off course searched for clues in the documentation, in the tutorials, and in the examples, and I Googled it, btw has a much better ring to it than I Binged it, seemed to me I was by far the only one with more or less the exact same problems. There was a pattern, that the same questions was asked by beginners, and attempted to be answered, over and over again.

I certainly would never expect, nor want, the JUCE/ROLI team to scramble and stop developing JUCE or SOUL, and only make additional documentation, but perhaps they can add bits here and there over time. What parts to prioritize can perhaps be found out by checking out the ā€œGetting Startedā€ forum, to see what seems to stumble beginners the most.

18

IIRC someone already did that in the past, but it was at the time of JUCE v1.xx and it soon became obsolete.

The problem with a book is that: the moment it is published, it starts getting old and it tends to do so quickly

2 Likes
19

Thereā€™s this one, but maybe not helpful for most of us.

20

Whaaat! Doesnā€™t everyone speak Japanese? Maybe I should start work on one in my native language Danish. It will then be widely accessible to me and that one other Danish JUCE guy - lol!