Hey, I am currently creating an alternative to the JUCE tutorials). I found it very annoying, that some of the tutorials are not standalone and require you to have a already setup project from tutorials before. I am aiming to create more standalone tutorials, especially made for the development of audio plugins. What do you guys want to see in those docs?
You can find the current version here.
1 Like
Good idea! I also think its time for the JUCE tutorials to get a bit of a refresher .. I’ll check out your project and send you some feedback.
Is there a repo, though?
My 2 cents:
make a beginners tutorial that walks people through best practices:
- use git (instead of downloading the .zip)
- use CMake (instead of Projucer)
Neither of those are difficult once you’ve been shown the ropes.
Although I suppose one argument against CMake is the context switching required, but that’s why I switched to CLion for my IDE. And of course the learning curve is steeper.
Fork also makes git a breeze and is well worth the investment.
Despite the steeper learning curves though, with the right guidance (a nice tutorial!) people get a much better foundation for “how things are done professionally”.
3 Likes
yes. here
Hey, I think writing something about git is very useful and also something about CMake. However since I personally don’t use CMake (yet?, maybe in the future), it will take some time.
Also I don’t think downloading via git is the best way, however it would make sence to show the reader this option. Thank you for your input!
1 Like
Very nice! I love the navigation with the menu on the left side, makes exploring so much easier.
Yes, I also think a tutorial about setting up and using git would be very useful. Git is an absolute must I would say, both for one’s own code as for working with JUCE, specially when one needs to make some mods to the JUCE code itself. With git keeping one’s changes whenever JUCE is updated is trivial. And even if one sticks to the simpler Github Desktop, git makes an enormous difference.
I don’t understand what you mean about downloading via git though. I think it couldn’t be easier.
1 Like
First suggestion: add a URL to the git repo in the sidebar, so that its easy to access for those of us who might contribute.
Second suggestion: learn git! It will rock your world if you make the effort. 
The URL for contributing is a good suggestion. Also I will add the git tutorial into the todo list.
Added a contributing page: Contributing - lemonjuce.
Initializing a repository and everything is essential, but I am not sure what this should mean.
Either to donwload JUCE via the git repository or to include JUCE into the git repository via Git Submodules. The first one would make sence, but I think the second one wouldn’t make sence for a beginner and is more something that advanced people maybe want to use or am I wrong?
Writing beginners tutorials for frameworks/libraries is always a challenge because there’s a big difference in being new to just that framework, being new to the language, or even being new to programming as a whole. With JUCE, it’s very often the latter.
In my own experience, it’s really frustrating doing a “beginners” tutorial that assumes you’ve never written a line of code before and so instead of explaining how the framework works, they’re teaching you what a variable is. It’s equally frustrating as a complete beginner to programming to go through a tutorial that assumes you already know loads of stuff.
It’d be a good idea to write separate “beginner” tutorials for each of those cases. E.g. no point confusing people about git if they’re new to programming, and no point confusing them with CMake if they’re new to C++.
1 Like
This is cool!
Can you elaborate on this, so I can better understand? Is the issue that they are PIP-centric and that’s confusing? Or that sometimes they are multi-part and depend on a prior PIP? Or do you mean you want something like at the end of the Projucer setup prefacing every tutorial topic?
I recently moved the official tutorials out of doxygen into markdown format (published via Wordpress) to make them more reader-friendly and maintainable. I would like to spend some time updating their actual content too, so I’m also interested in hearing what people would like to see improved.
I feel you on this, but I’ve come to learn that actually there are many pros (er, big indies at least?) that swear by Projucer, even after having done some CMake wrangling.
100% to this. Part of what you want to learn as a beginner is what the conventions are and what choices you need to make. A round-up on the differences between Projucer and CMake would be useful, as that’s one of the first choices people need to make.
I like this idea. For someone like like me, with prior git and command line experience, I definitely wanted the CMake + git path and didn’t want to deal with downloading PIPs (would have been happier referencing a repo).
1 Like
Exactly.
I think it would make sence to write a tutorial for git and cmake but not as a complete beginner. When I started out, I was glad to use a GUI instead and for my first projects, git was not really well suited, since most stuff didn’t work. I didn’t use git even tho I did know how to use it. I just didn’t see the point in it, when it just got deleted a few hours later.
When I first started out, the problem with the official tutorials are, that they are not standalone. Standalone in a sence of I cannot just copy the code but the project and I most likely must have created the project in one of the tutorials before that. If I for example, just want to know, how to draw audio waveforms, I needed the project already done, since the tutorial assumes, that you already have some code. This got quite confusing over time and as a beginner in C++ too, I often didn’t know, what the issue was. I am a programmer for 3 years and all the docs, that I read through were quite standalone. Laravel is a good example. If I want to add something, I just search it via google. Then most likely the docs will be recommended and there are the code snippets and where to add them to add the feature to my application. Also there is an explanation on to why it works.
I noticed this! I really like the new look and I really enjoy it.
I think it would make sence for the tutorials to just be quite “from start to end”. So when I start at the first page, that I should go to the second page and not the third. This got me confused too, because I wasn’t sure, if I just could skip one because I just wanted to create an audio plugin and not a standalone audio application.
Totally agree. It doesn’t make sence to throw a CMake file at a complete beginner in C++ and JUCE. However, I would also think, that it’s a good idea to “hold the readers hand”. So if he has zero familiarity and doesn’t know what to choose, that there is a suggestion or a clear path, that he should use Projucer in this case. With two tutorials, that have the same output, a beginner might get confused and frustrated.
From my experience, its easy to read every Projucer tutorial, even tho I want to use CMake but not the other way around. So I think, it would be best practice to just write everything, as if the reader would use Projucer. For CMake stuff, there could be a own section on how to do that. The tutorials should be mainly focussed around the tools, that JUCE provide and not any third party tools like CMake. If anybody chooses to work with CMake, its the CMake’s docs job to teach the tool to the person in my opinion.
EDIT:
I like the concept of PIP files but this too can be quite confusing as a beginner. Why should I use a .cpp if anything can just be written in the .h? I personally never used PIP, but its quite cool to have such a feature. But as a beginner I want to have everything lined up with the tutorial and when there are complete files missing, its just confusing.
1 Like
Mainly just to download, because then updating is just a git pull, but also even if you’re just a solo dev using git to manage your own code comes with so many positives that it’s just something every newbie should be told to learn from the outset. You can get by with the basics and benefit, and if you find yourself in a pickle you can’t get out of there is always the nuclear option:
I’m not a fan of submodules at all, which is also why CMake becomes incredibly useful. I use CPM to make getting and using dependencies simpler than vanilla CMake.
2 Likes
Thanks for writing that all up! So to summarize it sounds like you are saying a couple things:
- For individual tutorials, it’s unclear if they contain all the code you’d need to copy and paste to do the thing, if you’d need to have done a prior tutorial, need a fresh projucer project (standalone? plugin?), if there’s additional code in the PIP — the dependencies could be clearer, especially when you have an existing project going and are debugging.
- When walking through the tutorials as a whole, they feel disjointed (many not built to flow into each other, they might use different project types, some are clearly multi-part).
- Many of the tutorials are multi-part or build on each other, but it’s not clear enough that you’d have to go back and do the old part. For example the waveform tutorial builds on the audio player tutorial, but you might already have a project that you just want to add a waveform display to.
The main value I got out of the tutorials when I originally started was “a place to check how things come together,” or “what API might be used for something like a waveform display,” etc — Like you, I wasn’t looking to go through a big specific complete project flow, I just wanted chunks of code I could copy-paste to get a starting place I could understand.
The Laravel docs are great! I think it’s best to see that as a different category of docs: API docs. Unlike API docs, the JUCE tutorials are “goal oriented” and center around walking a user through building a small but complete compilable example. The Laravel API docs hand-hold you through each section of the API, providing useful code snippets and example code.
API docs are my favorite type of framework documentation. I believe it’s the most useful and empowering for developers, as it enables devs to show up, understand a concept, grab some code example and go. The rails guides are another good example — they fill the gap between the in-source per-method documentation and something more encapsulated like a tutorial.
I’ve experimented with these types of docs for new JUCE 8 features which are more along those lines: what do you need to know, what does the API look like in usage, etc. Note: that animation doc isn’t aimed at JUCE beginners, it was written to introduce the feature to existing JUCE devs. But I can imagine fleshing out that documentation to be more friendly, putting it in-context with a bunch of other API walkthroughs with examples, and we might end up with very useful API docs similar to rails/laravel…
Thanks for the feedback! I might DM you privately, this has been motivating me.
1 Like
Yes, you understood me absolutely correct. The example with a “walking a user through building a small but complete compilable example.” is the perfect term. If I want to find something in the docs (tutorials), I want to know how I can implement them into my project and not into a already made project, with some classes, that might not exist in mine. Maybe those are just called different but there is no indicator in the docs to tell me that (for ex. PluginEditor and MainComponent). Docs like Laravel or rails guides would be perfect and would’ve helped me even more than the current tutorials. The lemonjuce project is a collection of the notes, I created for myself so I can “walk myself around the building” again and don’t need to find every piece of the building in a book, the forum or the tutorials.
If I can help you with writing or ideas, I would be glad to help!
I agree, if you know git, it can be very fast but you would need to compile the Projucer app and this is likely not very suited for a complete beginner. Also you need to keep in mind, that beginners are often afraid of the terminal and learning another application like fork or github desktop would be another application, that they need to learn. Learning how to use git would not make sence in a guide on how to use JUCE. Just provide some info, that this can be done via git, if wanted.
I think the most important issue is, provide the tutorials in working form as a git repo .. this way folks have a good reason to learn git, and it doesn’t have to be all command line - Tower works great, there are plenty of great alternatives, even just throwing CLion or VScode into the mix, a user can learn git…
1 Like
Also allows people to contribute to updating the tutorials with newer best practices as the framework changes