Hello Everyone,
many members of our developer community have criticized our SDK documentation. And rightly so!
To cite just a few of your requests:
“I spend days looking up this stuff sometimes. Even with the search functions in the C++ docs the relations between things just don’t really come together sometimes.”
“Why do I even care about these markers? What purpose do they serve in the grand scheme of things?”
“I just wish they would put more examples in the SDK”
“I find myself annoyed about missing information in the SDK documentation very often recently, because I had to invest a lot of time figuring out these tings myself.”
“But i don’t know where to start. The documentation is very unclear if you are a beginner to plugin development :(“
We heard your complaints, made a plan and worked quite hard to come up with a first bunch of improvements.
Today, we uploaded an extended C++ SDK documentation, which will provide you with some insight of what we have in mind.
Note: If you run into troubles with the updated docs, please check/clear your browser cache.
The General Concept
Before we basically had a mere API references with some additional information sprinkled in between.
In future, we plan to have “Overview” articles and “Manual” pages. For most topics and tasks you will find small code snippets demonstrating the usage of functions and classes.
“Overview” articles provide an About section, briefly explaining the broader context and concepts of a field of interest, and links to related classes and “Manual” pages.
“Manual” pages on the other hand explain classes and their context in more detail.
Today’s Update
With this update, you get such “Overviews” and “Manuals” for the most basic datatypes and classes. But please rest assured, this is not the end, it’s just the beginning. We are already working on such articles for more advanced classes. The end goal of course is to cover all classes, but we won’t be able to deliver this in one step. We’ll continue based on importance and relevance for most of the developers and will deliver updates from time to time, whenever we feel a certain field of interest is mature enough.
Update Details
There’s a new “Basic Knowledge” section under “Overviews”.
In this section you find:
- General Plugin Functionality – Most important basic functions of Cinema 4D plugins
- Foundation Classes Overview – Most fundamental classes and concepts of Cinema 4D’s API
- Data Types Overview – Most important data types of Cinema 4D’s API
- BaseDocument Overview – The class representing a Cinema 4D project
- Scene Elements Overview – Objects and Tags
- Materials and Shaders Overview – Classes defining the surface properties of scene objects
- Animation Overview – Keyframe animation of parameters
Feedback Welcome
In the end, we are making these changes for you. So, we are especially interested in your thoughts on this new concept. Taking the involved amount of work into account, it would be fatal, if we ran into this direction, while everybody wants something different. Also we are aware there are many other places we need (and want) to improve on (search engine, page style+formatting,…). We’ll address these separately, for now, we are really interested in feedback on the new concept and the new parts of the SDK documentation.
Cheers,
your SDK team
FeedBack? Ok, but remember you you asked for it. 🙂
1.) I don’t see a link to SDK examples in the online docs(if it’s there it’s hidden too deeply)
2.) You are doing a good job documenting things for users who already know how to read SDK’s. But IMHO it’s still not “Newbie” friendly. The more things you document in your current style. The more confusing it gets for a newbie to understand it all.
When it come to newbs. You must keep it simple. And right now the docs are a massive pile of unconnected dots that need to be connected.
I have two recommendations:
-Every class has functions that we use to write plugins. So every class should have a simple working example in the docs showing how all of those functions are combined together to produce a result. Right there in the docs(see the Qt docs for an example).
Doing this will answer 90% of the questions asked in the support forum.
-For the newbies. I think you should handle that issue separately. It’s a very hard subject to tackle.
As someone that only recently learned how to read SDK’s I can tell you that was the most difficult thing to learn. Harder than learning the actual C++ syntax.
If you really want to help the newbs. IMHO you must teach them how to not just read the docs. But also “interpret” them. Because simply reading them will not be enough for them to use them.
Although. Putting code examples in the docs like I suggest(See Qt) will greatly help them to just read->copy->paste->succeed.
Even though I don’t think your current system is newb friendly.
I admire you guys for even attempting to address them. Because it’s a very difficult task.
Every person has their own problems to overcome. It’s like trying to teach everyone on the internet how to play an instrument with a manual.
I hope I wasn’t too rough on you guys. All of your work is appreciated.
-ScottA
On second thought. I think I misunderstood what you guys did, and was a bit too critical.
I wish I could edit what I posted earlier.
After looking at it for a while longer. I see you did add a lot of example code that should be of great help for newbies and people coming from other programs.
I was expecting to see new example code throughout the entire SDK. But now I see that what you did was create examples for the most common classes and functions.
That should be very helpful.
Hi Scott,
thanks for your extensive feedback. And for even taking the time to put it into another light. Reading your first comment, I thought, we had failed completely…
We are already thinking about articles for newbies as well. Of course we will never be able to provide something, that will work for somebody who has no programming experience at all. And I don’t think, this is our job. But we are certainly planning some more introductory stuff.
Cheers,
Andreas
Yeah. I feel bad about my first comment. Because I didn’t look hard enough at it before commenting.
As long as you keep adding code examples to show how to combine the SDK classes & functions. I think you’re on the right track.
Now I have to go see a doctor about removing my foot from my mouth. 😉
-ScottA