API documentation without code samples is essentially pointless.
I have started clicking the “This page needs code samples” at the bottom of pages that don’t have code samples.
However for some parts of the API that means every page !
Please couldn’t we just take it as understood that every page of API documentation needs to have code samples, and then remove the “This page needs code samples” button, and the need for having it?
But that’s not really true. Lots of things are self-explanatory, and one code sample can cover multiple things at the same time.
It shouldn’t need a code sample if the description is detailed enough: telling what it does, what you input, and what it outputs (the standard stuff that pops up when you type “///” in Visual Studio before a method).
Unfortunately we run into situations where even those things aren’t included, or there are hidden gotchas that wouldn’t be helped by a code sample (like physics overlap with concave/convex stuff).
Not all samples are created equally, at any rate. It’s trivial to add a sample that is no more illuminating than the API documentation. It actually takes some thought to create samples that provides enough meaningful context to be useful without also being excessively verbose.
“essentially pointless” is an exaggeration. They are certainly helpful, but often how to use something is explained well enough in the description. The ones that really bug me is where there is no code example, and a 1 line description which basically tells you that what it is for (which sometimes doesn’t tell you anything you couldn’t already figure out from its name).
One problem with code examples, is they are something else which needs to be maintained. How you write the surrounding code can change in a new version of Unity, even though the specific line of code the example is for hasn’t changed.
Ok, one code sample can elucidate multiple API calls … then please could there be a link to that one code sample from each of the API reference pages where that code sample is relevant ?
My point is that API reference pages that follow the form:
Dog … has a property … Legs.
Legs are the Legs that the Dog has.
doesn’t tell me anything about either Dogs or Legs that I can’t already tell from code completion.
I can see from code completion that a Dog has Legs.
That does not help me one iota.
Now everybody who already knows how to use the API, knows what a Dog is for and how to use its Legs property.
But for everybody who doesn’t already know how to use the API (ie. probably everyone who is looking at the reference documents) this tells me nothing that I can’t already guess.
Just pulling the first one I could find but when trying to learn ECS/DOTS there are a number of pages that just say “TODO” in descriptions like under “Using Animation” says TODO
https://docs.unity3d.com/Packages/com.unity.animation@0.2/manual/index.html
I get it’s moving fast but a usage example would help a lot. A million developers solving a basic problem versus the person with experience who wrote the thing provides a simple usage they probably use for testing it before releasing it?
What do you need to know about the dog or its legs that isn’t already clear?
For example, a transform has a position Vector3 property. What else needs to be said? You already know what it is and what it’s for without any example.
Only some API needs examples, and really only when the the fundamental concept of its functionality is unclear.
You click on “Legs” in documentation and read what “Legs” is. The page will usually explain what properties are within the class.
Code completion is not really a good form of documentation, by the way.
This has become somewhat of an industry standard over the past several years, sadly.
Apple’s documentation of APIs is particularly full of this kind of not-done stuff and has been getting worse. It’s to the point of being a widely known standing joke.
Rigour and honour have gone from APIs and Frameworks.
The exceptions prove the rule.
Further to the OP’s request:
Performant, Optimised Examples, PLEASE!
Examples need to be done with a view to “Performance by Default”, especially in the MonoBehaviour word (pre DOTS), as that’s where the most gains are possible by simply not choosing one of the many ways to do things inefficiently. This would also serve to generally ‘teach’ how to get the best out of Unity to the most possible users in the easiest possible way.
Play Examples in the Browser, PLEASE!
Unity outputs to webGL → there should be a “Play” button inline with examples, to see it happen instantly, and experiment with values surfaced via editable sliders etc. This would prove what’s what, and help with comprehension and learning in enormous ways, and build confidence in the webGL capabilities of Unity (a very unique capability for a general purpose engine).
Sorry, but anyone, who can’t figure out what is what based on the source code and some samples, shouldn’t do anything with preview or experimental features.
I agree, we need to demand consistently high quality documentation. For the officially released, finalized features. Not for the 0.2-preview.
Man I think ppl never worked with custom frameworks / engines. Documentation is myth there and You have to handle it :). We can say all bad things about Unity, but their API docs are superior to anything.
The defunct Stingray Engine had next level better documentation.
But even just staying at the Unity level of docs, checkout how fast, fluent and easy to navigate this is, from the little old Corona engine, now called Solar2D:
https://docs.coronalabs.com/api/library/audio/loadStream.html
This is called “poorly done” and not “easy to navigate”.
Here is the the right way to do it:
https://docs.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetspecialfolderlocation
See this massive index to the left? It is important. As it allows you to navigate to related nearby pieces of documentation, and also it allows you to see at a glance EVERYTHING this section of API can do.
Unity has this handled.
You didn’t look quite long enough.
Corona/Solar2D uses the familiar and superior cookie crumb navigation, along with a root:
https://docs.coronalabs.com/api/index.html
… and down a level, all relevant stuff on the left:
For starters, is it world or local space? The name is ambiguous and to a newcomer it could be either.
What happens when we read from or write to it? Since transforms expose both world and local positions, which one is it storing and which one is it calculating on demand? When does recalculation of one from the other take place? If we make changes which are propagated to other transforms, when does that happen - immediately, or at some other time?
This goes past saving time of developers experimenting to figure it out for themselves. We’re talking about real time applications here, many of which are run on limited hardware. Details matter.
This is reasonable, but this:
Would normally go to class overview.
Also none of this can be explained through code samples.
That’s not what examples show.
You’ve probably picked the worst possible example to make the case that examples aren’t always necessary in API documentation.
Documentation explanations should be a specific form of writing that explain a thing, abstract from it. Done well, within modern online documentation’s nesting and hierarchical flexibilities, this permits any point of a complex system to be a suitable entry point to the whole.
Each explanation should use the least possible terminology and require the barest possible prerequisite knowledge to be understood.
Nothing can be explained by code examples, only demonstrated and (hopefully) clarified in ways it is hoped the reader can interpret such that they’re able to determine cause and effect from what they discern is going on. Ideally, this occurs in ways suitable to their combined perceptions and contexts of why, how and what, when and where.
If you can’t write an easily understood, reasonable English explanation of a programming principle, engine feature, function, API, process, paradigm (or any other aspect of game making activity) without resorting to code, you probably shouldn’t be writing documentation alone. You’d best serve readers by teaming up with someone able to write things well for maximum traction, reach, resolution and responsiveness.
If, on the other hand, you only care about advanced users, a dry reference without explanations might be sufficient, so long as it has good examples.
Unfortunately, because Unity relies on subscriptions, we’re in the worst of both possible worlds. wherein they have a vested commercial interest in delaying gratification and taking users through the longest sustainable path to productivity that’s possible. The shortest paths to user comprehension and proficiency within their systems are not in Unity’s best interests. So long as they can constantly proclaim and convince users it’s their own fault for slow progress, this works quite well. Sadly.
Vector3 and position are so ingrained into Unity usage that there’s no better place to start clarifying and validating explanations with demonstratory examples.
I discovered the power of code examples when I taught software courses.
I discovered that most people who came on my courses stayed happier when I kept explanation to the minimum and examples (typically code examples) to the maximum.
I’m not a qualified educational psychologist or anything, but I would assume the reason examples work so well for people when learning unfamiliar information is because they communicate information at a more concrete level, rather than at a more abstract level. I discovered that if I gave people enough examples first, they would be set up to absorb the abstractions and unifying conceptual generalizations which the specific examples were examples of. Whereas if I gave people too much explanation prior to examples they would typically just get annoyed or even angry.