API documentation without code samples is essentially pointless.

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/wi...ore/nf-shlobj_core-shgetspecialfolderlocation

Spoiler

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.

Spoiler

 

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:

https://docs.coronalabs.com/api/library/audio/index.html

 

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.

 

I don't mean this to be rude, though it will sound like it is.

There's two other possible explanations that jump right out:

1. You're relatively better at choosing and/or designing and demonstrating examples than explaining things

2. Your audience is less theoretically/abstractly inclined than they are fond of discerning through examples

The most likely case is a blend of both being the key factors in what you're experiencing.

 

Perhaps, for the benefit of people who want examples, there could be examples.
And the people who don't want examples could just ignore and skip over them?
I guess they could put code examples in expandable sections in API pages,
and then the people who don't want examples could simply just not expand those sections.

 

I agree, it's not, it's more the "what else needs to be said?" attitude I was replying to than the specifics of the conversation. There's a heck of a lot more to be said than "a transform has a position Vector3 property". Whether it's said by examples, specification documentation, descriptions, interpretive dance... it's definitely got to be said.

(My preference is for specification docs.)

 

Oh yeah for sure, documentation should explain even things that are supposed to be obvious. I was referring to there being nothing to explain about how to use it, not what it was.

 

I believe this attitude wrong, and unhelpful to those in need of the most help, at the most crucial stage of the Unity user journey.

Transforms are one of the first and most important things to understand within Unity, and Position is the most significant of its properties, and one of the first things most new users will attempt to do something with, almost certainly to make something move.

It is without equivalence in ability to serve as ideal introduction to:

1. GameObjects
2. Unity Components
3. User Scripts & MonoBehaviours
4. Engine Callbacks & GameLoop
5. Referencing & Caching References
6. Animation, Time & Coroutines
7. Nesting, LocalPosition and Prefabs
8. Object Caching and Pooling

 

I'm not sure I understand what you're getting at. This is about examples, not documentation in general.

 

Sorry, I should be more explicit.

Unity's first claim was "democratising game development" or some such waffle. Which strikes me as being akin to "Don't be evil." in terms of the amount of irony and sarcasm seemingly smothering these catch phrases.

Now, it's "performance by default", which is something they can claim twice, because all the documentation's examples are either the worst possible performance way of doing something, or well within the top 3 worst ways of doing something.

Ergo, examples of how to use position can entail all manner of things, across increasingly complex examples, that serve as both examples of doing things with transforms and position, as well as all the other things in the list. And examples should show things being done optimally, by default.

In the first instance of a new user coming across position in the manual, the full sequence of these examples should roll out below their initial readings, each bringing in more of the points on that list, as idealised demonstrations, examples and exemplary insights into the optimal way to do each increasingly significant process.

All the way to pooling.

Later in their learning journey, the new user goes to the page about GetComponent<>, where they're re-exposed to the same exact example on position, via caching transforms, and can now learn about the importance of what they've seen in this example.

Other examples under GetComponent<> might introduce other significant aspects of hierarchies and explain the nature of dependency and link to some insights into how to prevent chasing one's own tail. etc.

 

I'm still not clear what your point is.

There are some things that need code examples, other things that don't. That's all I'm saying.

 

Using transforms needs examples more than any other single aspect of Unity.

Position is the most used of the transform's structs, and needs examples more than any other within Unity, for several reasons.

One of which is that it's a struct, and caching the transform increases performance significantly.

Another is that dot products are slower than doing individual modifications, despite being messier.

One more?

You need to get a reference to cache a transform. Learning about transforms is the ideal place to learn this "performant by default" approach to using components.

Getting it yet?

 

https://docs.unity3d.com/ScriptReference/Transform-position.html

 

Did you miss the nuanced sentiment that examples would better serve users if they helped them see and do and learn the best ways to do things?

Or just the part about caching transforms?

 

@april_4_short please stop making dumb cubes of developers.

The purpose of docs is to bring minimalistic and basic idea, what is for.
And that what it transform doc does. See Joe's response.

In fact, if you want more about transforms than that, click any search engine and search for answers. That what most newbies does, rather than look into docs anyway. Teach how to use fishingrod, not feed with fish.

Saying that, there are areas of docs, where any sample is missing. And more than anything, I would require most simplistic example, to keep going.

Dev programmer should use also an itelisence, which shows overloads and often explanations of specific methods. Not ideal, but is grand help already. Teach people to use that.

Again few clicks into any search engine, gives most of the time extensive explanations.

If you want caching and pooling, this is an optimisation area. And much more advance topics. On top of that, it has nothing to do with transofroms directly, as of examples. You can optimise and pool anything. Transforms are heepen to be most common one.

 

Should Unity's documentation also teach math and computer science and programming itself?

 

Should the forum teach understanding, compassion and reasoning?

 

Although perhaps not the best (ie. worst) example, this seems to me to be a reasonably good example of "Dog-has-legs" documentation ...

https://docs.unity3d.com/Packages/c...e.XR.Interaction.Toolkit.XRRayInteractor.html

 

It helps me see, again, that XR, VR and AR didn't fail for lack of effort.

 

No, it doesn't.

it is a basic concept, and because you use it or something like that all the time, you'll spend 3 second reading what that is and that will be it. There are more complex concepts and things that actually need an explanation. Transform.position isn't one of them.

Trying to act sarcastic means you're losing the argument and running out of things to say.

Also, there isn't the best way, and I'm a user too, except that I don't need any extra explanation there.

Using a game engine requires a brain, an ability to learn and some basic aptitude towards necessary tasks.

While it makes sense to put sufficient effort to provide documentation to user, it absolutely does not make any sense to explain things from the very beginning, because people with aptitude and necessary skills already know this stuff, and those who don't are less likely to bring any money or finish a project in the long term. The purpose of a company is to make money, and it makes sense to target professionals and skilled people as a result. So as a result script reference is written for people who can program (at least somewhat), and dealing with transforms will require familiarity with matrices and vector math.

By the way, this is what great unity documentation looks like:
https://docs.unity3d.com/Manual/ExecutionOrder.html
This is probably one of the most useful unity pages I had read to the date, and I keep revisiting it often.

 

By definition, if you have to keep going back to it, it's not good documentation, it's merely reference material that you find it necessary to keep revisiting because the documentation isn't good enough.

Good documentation would find a way to help you remember the sequence, just like KISS helps you remember "Keep it Simple, Stupid", or PEMDAS helps with:

• parentheses
• exponents
• multiplication
• division
• addition
• subtraction

 

Regarding that sequence, trying to memorize it would be an incredibly stupid thing to do. Because the sequence is not set in stone and is subject to change. And it will change at some point in time.

Also, you're asking for the impossible.
It is not possible explain in simple terms something that takes 15 years and hundreds of people to build.

For example, take the Library of Congress. Reduce it to a single acronym that correctly represents entirety of the information stored in there while losing not a single piece of information.

That's what you're asking for.

The reason why I keep returning to that page is because it is not possible for a single human to keep every detail of the engine in their head. You forget things, and things that you do remember are not always the most up to date information. The maximum program size where you can still remember everything and keep every quirk in mind is about 200 kilobytes of program text. The engines are in hundred megabytes range. I don't have unity source access, but unreal is 300+ megabytes of program text, and that's literally telling computer what it should be doing.

So, 300-600 books worth of text which are constantly being rewritten while you're reading them.
And you want to to simplify that.

 

This is such a gross distortion of what I'm communicating that I have to wonder why you're going so far out of your way to create an alternative interpretation of what was written.

Let me break it down, in the hope it's clearer.

Examples are good for various reasons:

Many functional things benefit from examples because their operation is quite literally revealing of their purposes and potential, their usage and machinations.

Many types of people benefit more from examples than explanations and descriptions - for various reasons

Many technical writers struggle to articulate descriptions well, let alone explanations, which require significant iterative and explorative experience and empathy, plus the ability to write engagingly, which is an art. One that I clearly don't have.

Many attracted to technical fields are inclined towards tactile engagement with the mechanics and operative methods, regardless of descriptive and explanatory writings, both at the incoming level and the top streams. Why not let them talk in their own language of examples, to each other, across generations.

Potential limitations of various languages and EAASL users are most assuredly overcome by demonstrative examples closely tied to the descriptive and explanatory documentations. Further, it's time consuming and difficult to get good/great translations of technical documentation to all major languages, whilst examples are somewhat universal.

Unity struggles to get Documentation done for many of the new things it's doing in any language, so we might have to make do with analysing their unit tests as examples, in some/many cases.

Unity has a webGL player that can inline a running demo of examples! This, alone, should be reason to have examples for everything and a live coding environment to make minor modifications to help further solidify and empower understanding and insights.

Evolving examples, that build from basics, provide enormous insights into the Engine and the best ways to use it in the shortest and most assured manner. Designed well, these evolving demos and examples can cover the full spectrum of the engine's abilities in a minimal branching manner that retains recognisable and familiarising encouragement to code in the best ways to get the most from Unity.

Frankly, it seems extraordinary, to me, that anyone would argue against any aspect of improving documentation, especially examples, despite personally being one of the folks that would much prefer good explanations and great descriptive prose.

 

Then express yourself better.

The engine is huge. Things change. If you focus on documentation alone, you'll be left behind in features compared to competitors. The docs will never be full and complete.

Therefore you're expected to have some skill and not require full and complete explanation of every single detail.

Neither empathy nor engaging is needed in API docs.

And non-native speakers will have to learn english if they expect to get anything done in programming field. There's no way around it.

The issue here is that many things you propose do not look like an improvement. That's why there are arguments against your position.

* An example for transform.position? That's not needed. Someone already wrote one anyway, though.
* Engaging and empathy? Unnecessary. The docs are a reference book. The job of a reference book is to get to the point without wasting time, not entertain.
* An example for every single thing? That's an unproductive waste of time, as not every thing needs an example. Some are trivial.
* Mnemonics or whatever it was for order of execution page so I memorize it? Also a waste of time, because the information on that page is transient. It is there today, but it may be gone or outdated tomorrow. There's no reason to commit it to my permanent memory.

I may be oldschool, but in my opinion, a developer is supposed to have some skill. Meaning there are things you're expected to know, and if you don't then it is not documentation's job to explain them to you, but it is your job to learn them on your own, because they're beyond the scope of the reference. And if someone is a "newbie" then their next goal would be to improve and stop being a newbie.

At the moment, for the core of the engine, the docs are decent. When we move away, the quality seems to be deteriorating, which is something unity may or may not address in the future. Preview package docs? Well, those are preview for a reason, and you're basically suppose to read the code repository and infer how it is being used without being told. If you can't, you aren't the target audience and should wait till they stop being preview.

In short, there are areas where the docs could improve, yes. But there should be some minimum expectation of developers skill because trying to accomodate everybody will cause the docs to deteriorate instead. And tha'ts the reason why docs shouldn't waste time explaining math covered by school math course, for example.

P.S. Personally I would prefer if the engine opened up and provided source access. Because code can serve as documentation when something is absent or not mentioned. Unfortunatley, this is unlikely to happen.

 

It's not a zero sum game. Work doesn't slow down on the engine because folks are hired to explain the engine.

As to the rest, I can't significantly differentiate it from gatekeeping and further, seemingly deliberate, straw manning.

 

Perhaps it might be handy to see where documentation has moved onto in the rest of the world, to realise just how far behind Unity's docs presentation and content is now lagging behind what's possible:

https://www.twilio.com/docs/usage/api

https://stripe.com/docs/api/payment_methods/create

https://docs.github.com/en/rest/reference/gitignore#get-all-gitignore-templates

https://dropbox.github.io/dropbox-sdk-obj-c/api-docs/latest/#route-specific-errors

Notice things like the colour codings, linkings, speed of navigation, layouts, spacings, scrolling performance, and great examples.

 

It sounds like you think it should teach English, as that prerequisite knowledge for participation here.

The point is that most tools, skills, etc. have prerequisites that people need to meet in order to effectively use or do the thing. That's not "gatekeeping", it's the nature of the world. Unity's job is to make and supply tools. People need to have certain skills and knowledge before those tools are useful. There are plenty of sources and places those skills and knowledge can be developed from, including other people and/or businesses who will help you, books, and oodles of free information online (of varying quality).

For what it's worth, Unity does have resources to teach a lot of the math, programming and other skills required for game development. It's not in their manual or reference guides because that's not where it belongs.

By what definition? It sounds very much to me like you're confusing "reference material" with "training material". Those things are not the same. After I learned about spatial transformations I didn't have to keep referring back to whatever materials I learned it from because I had developed an effective enough understanding in my mind of how it worked. But I don't want to memorise the specifications of every API call in Unity, so I refer to the documentation whenever I'm working in a new or updated area and need details.

And on the specific note of examples, I would 100% prefer complete and correct specifications and descriptions than a bunch of examples. I don't want to infer how to address my use case by looking at someone else's solution to something else. I want to know how the core of the thing works so that I can apply that myself. Having examples as well is often helpful, but they don't at all replace having solid, complete, reliable specs.

 

We agree on this, one million percent.

And then some.

But I also understand the people that learn and conceive of how things work through more tangible interactions and examples. I'm not one of them, otherwise I'd probably spend all my time on Github and not need docs at all.

Or reference materials.

Which are a part of docs.

Good docs help the reader remember things, through many means, one of which is the ability to conceive of how things go through time, in any complex system, and why priorities are what they are.

This is the sharing of reasons, which can be a bit like learning to fish.

There's others, like what you've described.

Deliberate misinterpretation?

 

It does. Because the more documentation there is, the more it is going to lag behind the state of the source code. The unachievable ideal (one of the unachievable ideals, anyway) is self-documenting code. Where source code is available, and documentation does not exist, because you can dive into source and quickly understand how it works.

3 out of 4 projects you provided as an example, as far as I can tell, are TINY.

The final example is dropbox, and looks like that one would be annoying to deal with. That's because the code is poorly structured in the navigation bar and most of the docs resemble a doxygen dump.

I mean isn't this what somebody criticized unity for?:
https://dropbox.github.io/dropbox-sdk-obj-c/api-docs/latest/Protocols/DBSerializable.html
https://dropbox.github.io/dropbox-s...est/Classes/DBFILEPROPERTIESPropertyType.html

You want gold standard large scale, that would be MSDN and Qt.

https://docs.microsoft.com/en-us/
https://doc.qt.io/qt-6/classes.html

Accusing me of random things doesn't prove me wrong.

Like angrypenguin said, in the end it is a reference. Not a school text book. And knowing how to work with references is your job.

In the end, the engine is a highly specialized tool. If you want to use the tool, you have to meet requirements in skills. Working with reference documentation is one of those.

 

Gatekeeper beats chest!

News at 11.

It's only a highly specialised tool because they're poor at explaining it, and designing it (see Mecanim).

The more general they can make it (by design, execution and description) the more users, the more money... and the more consternation for gatekeepers.

Don't worry. There'll still be the mess that is SRPs for you to profit from.

 

No.

We're talking about documentation, but you raised examples including KISS and PEMDAS which are mnemonics used in training or teaching. People aren't "misinterpreting" you as some kind of attack. It's perfectly legitimate for people to disagree about stuff.

Are you familiar with the Dunning-Kruger Effect? I agree there's plenty of stuff worthy of criticism, but no, this stuff is legitimately a body of knowledge which is both broad and deep, and undergoing consistent change. Formally or otherwise, people study for years to get started at this stuff.

On the other hand... if I'm wrong and you are legitimately gifted enough to explain it well enough that it becomes a non-specialised tool then there'll be plenty of opportunity and probably quite a bit of profit in it for you. Have at it.

 

Having reflected on it, I think I want to take back what I said at the top.

I realize now that code samples are much more important on some pages than they are on others,
and I guess there does need to be a way of guiding effort so that pages where code samples are most desperately needed have them.

 

You're out of arguments, congratulations.

No. It is literally big and complex and cannot be simplified and made accessible for everybody.

I already gave you the "reduce library of congress to a single acronym" example and it is literally that. The current state of docs for the core is close to being the best that can be done.

Try writing your own unity engine. With 100% feature parity. In about 12 months you still won't be anywhere closer to being done, but you'll gain a bit of understanding of the complexity of the problem, and maybe it'll click for you why things are in their current state.