Unity documentation quality.

It hasn't gotten an official "what could be improved" thread yet, but the Unity documentation has continued to decline in quality in Unity 4.5 (despite the new look). When a release contains new features, those are the most important thing to document. Instead, we have:

Transform.SetSiblingIndex

void SetSiblingIndex(int index);

Parameters
index
Index to set.

Description

Sets the sibling index.​

Such "repeat the function and parameter names verbatim" documentation is worse than no documentation at all because it gives the false impression that the developer has finished documenting the function. I often come across such useless entries in the Unity documentation - in most cases (such as the above), I can get a rough idea what it does and work it out myself, but that's far inferior to being able to read proper documentation. Worse though is that more high-level documentation for this is missing - such as an example of how to reorder all children of a Transform, or some discussion of efficiency (since we can't see if the child list is a List, an Array, an LinkedList, etc.

This specific code is part of the Transform order now being relevant (especially in the upcoming new GUI, but also in the Hierarchy manual ordering feature of 4.5), but I'm using it as an example of the more general problem of new functionality receiving the least documentation.

 

Agreed, the documentation is shaky and outdated in many places.
And often many concepts are not explained in enough detail leaving a lot open to speculation.

Hopefully this is something UT will address at least when 5 is launched.

 

In the meantime, you can use the bug reporter app to report documentation bugs like that.

--Eric

 

That's great for individual cases but I think it's also worth some general attention.

Also, I'm tempted to suggest PHP-documentation style comment sections on each doc page. They're a great place for people to share useful tidbits that don't necessarily belong directly in the documentation but are commonly asked/looked for/causes of mistakes. It doesn't excuse Unity from getting the documentation correct and to a quality standard, it's just an in-line avenue for community hints.

 

No, Unity documentation is pretty poor. There are still some places in the documentation that link to nowhere.

 

It has its flaws, yes. Without suggesting that it shouldn't be improved, though, in comparison to plenty of other libraries or packages I've used it's actually pretty good.

Question for Unity: Are there staff dedicated to looking after the documentation, or is it purely a byproduct of other roles? For a living document this large I'd suggest it should be a dedicated role, even if not a full time one.

 

What places, exactly?

 

So Unity should write a simple program to check the documentation tree and count the wordage, highlighting areas that have a low word count. It could be another QA test they can run?!

 

It's been stated before, but we need a "Report Issue" button on every page, therefore the Q/A team isn't trudging through bug reports and it would be much easier for the end-user to report issues. I don't really have a huge issue with placeholder documentation being implimented(I'm gonna assume that's what the explain provided is, otherwise that is pitiful) as long as it is updated in a timely manner. The above is NOT ok, it needs to be fixed. Unfortunately it seems things like this is added to the "Fix when we have nothing else to do" list, and is never gotten around to. Isn't it about time we have a dedicated Documentation team working to fix these entries?

 

No. "More words" is not the same as "better documentation". Actually, that seems to be a common mistake made by people when there are complaints about their documentation being lax - they just go and put lots of words everywhere.

I love this quote, so here it is again:

Good documentation tells you everything you need to know and nothing you don't, and does so as clearly as possible.

Also, it should not be expected that people read references back to back. The use case is that someone wants to find out a specific thing that's important to what they're doing right now. So, it should be quick and easy to open the reference to the thing you need to learn about and, in just a few moments, locate the precise piece of information you need. High word counts actually make this harder. The same thing goes for lots of different types of formatting/font/hilighting/colours, walls of text with no headings or badly designed paragraphs, and various other things.

The whole thing should be clearly signposted, all the way. (This isn't just for the sake of readers, either. It's also key for maintainers, so that they can update the right thing, all of the right thing, and only the right thing.)

For the most part Unity's documentation does all of the above pretty well. Which is why I actually like it. Bits are missing here and there, but it's far better than having crap shotgunned everywhere.

Aside: Am I becoming like da baws with this new habit of bolding the guts of my main points like that?

 

AFAIK there's work in progress to dramatically improve the docs, and find a way for users to contribute. A community-driven effort would improve them no end. Of course such things would need to be moderated for wording/language though, but the raw materials provided by community would be good. I see this happen for other languages and like what I see.

 

PHP is a great example of this. I don't use it often, but when I do it's handy to have all the user comments right alongside the official reference. (It's kind of like the Dark Souls of programming languages - rough around the edges, it will kill you, and a huge part of the experience is relying on random snippets from strangers!)

Anyways, check out their page on comparison operators. Then read some of the User Contributed Notes down the page. Handy stuff, aye?

 

I personally don't feel that the documentation is good, but tbh it is enough to satisfy most of our needs at present. Although Some refurbishing in the future would be highly appreciated.

 

Unity should just hire a guy to work fulltime on handling documentation

 

They did; there's no way the docs would be remotely as good as they are if they hadn't. I'm not sure if you realize just how much documentation there is (a lot), and how long it takes to write all that (quite a while). Obviously there are some areas that should be improved, but by any reasonable standard most of the docs are at least fairly good.

--Eric

 

PHP's documentation comments are great. But if you Unity were to do the same, then they better moderate the crap out of them. Else every page will be stuffed with feature requests, price reduction demands, the mandatory "how do I fix a NullReferenceException error" and "how to access a variable defined in one script from another" questions, and the prerequisite refrigerator maintenance spam.

 

I wonder how the PHP docs maintainers prevent those issues?

 

The documentation has been one of my top sore spots for a while (less about presentation really, more about being up to date and thorough), but I can see where they're going with it and I think the new format is nice, and from what I can see there are signs of greater depth already.

Andy (Andeee) made it clear they have a lot to do yet, and have some neat plans, so I guess we just have to hang tight. Unity's pretty massive now, and we obviously have to keep in mind Unity 5 will need even more again - whole new render and materials pipeline, a whole new audio system, and so forth.

The question of collaborative documentation was answered partially in the How Can We Help You thread. The gist of it is, yes it's coming, but it probably won't be wiki style free for all. (IIRC it was more along the lines of vetted community contributions).

 

We do run checks for missing links. Prior to 4.5 we had hundreds. With 4.5 I forget the exact number but less than ten. Docs should be improving all the time. And yes, getting the docs editable by the community in some way is very important to me.

 

Maybe before a comment gets posted, it has to be approved by a moderator. That would help reduce the spam considerably and increase the number of helpful comments. Just my 2 cents.

 

I don't understand how the docs were not made correctly to begin with. Some of the example usages and descriptions are woefully inadequate. There must be internal documentation to Unity, or how do they know whats going on.

Maybe we should vote for certain community members to be allowed to add to the documentation. Then maybe also allow other users to submit documentation too, but with it being reviewed by those we voted for.

 

Maybe they moderate the crap out of them. Or maybe there's some sort of meritocracy in place.

 

Thanks for the feedback! Taking some of the first points in no particular order...

We have done a lot of work to replace old, poor-quality content, add new content and restructure existing content to make it much easier to locate. There is still clearly plenty of work to do but the docs have most definitely improved since 4.3.

You've found a specific example of bad documentation and I have no doubt there are others in the 4.5 release. However, documenting new features is the priority for every release.

We are investigating options for contributions to the docs from the community. Currently, we are leaning away from comment sections on the page and more towards a moderated system where we can incorporate good examples and corrections into the main text.

This is certainly being considered but we do need to establish that the users most likely to contribute will be confident using a tool like Github.

We are using an automated link checker for the docs from 4.5 and this has reduced the number of broken links dramatically, believe it or not. There are still a few issues, mostly with links generated in an automated way (this is part of how our doc infrastructure currently works and we have not been able to fix it all at once). We have a goal for zero tolerance of broken links in the published docs by v5.0.

It's not so much "fix when we have nothing else to do" but rather that the docs have previously only been easily updated at release (our old systems were heavily tied into the product build system and this was not helpful to us at all). The result is that fixes could remain unpublished for considerable time after they were made. The manual has already moved to a system that will let us make frequent updates. The script ref is still somewhat tied in with the product build but work is underway to remove that restriction too. We aim to avoid placeholder text in the first place but we should soon be able to fix cases where it leaks through.

Unity has a full-time documentation team, fully charged with the task of looking after the docs and improving them as much as possible. We've already made many improvements but the docs have come up recently (eg, this thread and Brett's "How can we serve you better" thread) as a target for improvement, so maybe we'll see the doc team expand in the near future.

 

While I, of course, wouldn't complain if they were improved, the Unity docs are among the best software API docs I've ever used.

 

As you say, we are probably even more vulnerable to junk appearing in the comments than even the PHP guys are. We are ruling out any kind of system that doesn't include moderation and we're also more keen to add edited content to pages rather than add a list of possibly useful comments.

We still have quite a backlog of stuff that was written before the doc team existed (and before our quality standards were in effect ). It's an ongoing task to get the old stuff up to scratch and also, as noted earlier, some new stuff does get through in a poor state. The issue is not that we don't understand Unity but that some of the text that you see was not written by diligent writers.

We're not necessarily going to democratise doc development along with game development, but it is likely that some users may be recruited for proofreading, "trusted" editing or other roles if they fancy the job.

And this is why you are the doc team's new favourite user! We realise we still have much to do but thank you for the vote of confidence in what we have done so far.

 

It would be cool if their was a system that could allow anyone to put forward snippits and if their was a rating system that would choose the order to display them, it would allow for easier viewing of how stuff works via code snippets.

 

Assuming the first version of the docs for new functionality is the responsibility of the developers who add the functionality, did the doc team approve such an entry? Or just miss it entirely? This is my point about stub docs being worse than no docs. The docs are good. Where there are holes, devs should leave holes, not paper over them to inadvertently trick the doc team into think all is good.

 

The reason for having stub docs is that when a mistake occurs (as with the new Transform functions), you know at least that the function is intended to be used. If it has no text then the meaning of the page is ambiguous. We don't want stub pages to make it through to the published docs but we believe a stub is better than a blank page or a missing page, as a general rule.

We are just about to introduce a new storage format for the script ref - it is ready to go but unfortunately didn't make the "cut" for the 4.5 release. Without going into the dull details, the new format will allow us to query and mark the doc entries in various different ways. For example, we will be able to check for short, incomplete or malformed pages, pages that don't have a code sample when they should, pages that haven't been expanded from stubs and various other monsters that have previously dogged us.

I should just add that I don't think the devs habitually try to trick us, btw It's just that communication about new APIs hasn't always been entirely effective, which is why are tightening the system up now.

 

I have to admit, there have been times I wish there was a "needs more detail, please" button on the docs. I haven't checked it out recently, but I remember a lot on the editor side being pretty sparse of info.

Occasionally, there are also cases where there is a little nuance missing. I spent at least an hour once to find out that apparently whole numbers return the same value from perlin noise. I don't know if I would have cared if it was in the doc, but I would have probably talked about it in a community area.

Perfect world Unity docs thinking here, if there was a community aspect to the docs, I would love to see two tiers. The lowest is the Q&A mosh pit that we expect it to be, while the second tier is the addendum to the main doc. It should be nothing but statements that get pushed (and probably edited for voice/context), which can further explain or go in depth on use cases or comparable features, etc.

 

I've noticed that when I do report documentation bugs they seem to disappear into the aether rather than ever make it into the publicly visible bug pages where they could be voted on. Is there any chance that bugs labelled as documentation could skip whatever review step is holding those up? It's not like they really need an engineer to reproduce them before the community sees the report.

If anyone is taking notes my current favorite is the AnimationUtility class which is completely missing documentation for at least half the methods.

 

That was just an idea for how to look for terse documentation that could need more work.

You could also have a user rating system, for how helpful the information is, combined with a comments system.

 

+1 for comments.

 

andeeeee, just want to say I like everything I just read from you. Sounds like there's further significant improvement to come, which is great news. Adding to what I and a few others have already said, it sounds like you're actively working on elevating the docs from "pretty good" to "best in class". Here's a giant thumbs up for that!

On the note of bug reporting for users, I agree that it'd be great to have something on the page rather than having to go to the bug reporter in the Editor. Also, a way to capture positive feedback would be nice. I think that Microsoft's stuff has a "Did you find this page useful?" question at the bottom of many pages, with yes/no + reason options. Have you guys given much thought to that kind of thing?

 

This sort of system would work quite well for pointing doc errors as well as submitting user comments. 2 birds, 1 stone!

 

I actually quite liked the new documentation. I think it is an improvement. Some need more/better examples but it is pretty good overall.

 

Yeah... just look at Source SDK docs.

We've got it good, here.

Still, we need a more direct process and link to the docs team so they can prioritise, given what the majority need.

Or is it that they have a mire of bureaucracy to follow? Does everything have to be super-approved or can they just make changes as they wish?

 

Hi @meat5000, welcome to the dark side.

I'm certainly a fan of the idea of letting cherry picked community members write suggestions for the docs that get checked and incorporated by the docs team. There are a few around in answers and the scripting forum that know the engine well enough to expand on the docs.

 

We should be advertising documentation roles in our Brighton office real soon... so anyone close by who wants to help, message me.

(Also, any one who's got docs changes to make/recommend, just send in a bug report with the text/code and it'll get merged into the docs.)

 

I came from a 2D game engine that had pretty good documentation and usually had 3-4 different examples showing how to use anything requested. When I started to use Unity and every tutorial says to always go to Unity Documentation and I would to find cases that had sometimes no examples, or no "useful" examples, and not very good explanations.

One of my biggest pet peeve's with Unity is the Unity Optimizing Scripts from their manual is not as useful as it should be, it should be AMAZING. I should find tons of examples, knowledge and benchmarks showing how bad stuff can be and even some wisdom on stuff that may shave off 0.00000001ms...anything that can teach more like:
Example:
Screen.width /2 & Screen.height / 2;
vs.
Screen.width * 0.5 & Screen.height * 0.5;

I understand the difference in performance will be negligible, but that doesn't the excuse the fact I want to learn more and become better at my coding habits. Ok I understand only profiler and objecting pooling is all I need to know in optimizing ( joke).

 

An important habit is not to obsess over the kind of thing you just posted. Don't worry about something until it's shown to be an issue. But test for such issues early and often, because the sooner they're found the cheaper they are to address.

Also, Unity can't make a one-size-fits-all amazing how-to-optimise-anything guide because optimisation is different in every situation. Something that really helps in one case could make things worse in another. Getting good at optimisation means being good at measuring things (the Profiler is just one tool for one part of this), finding bottlenecks, learning about the relevant underlying systems and problem solving to improve actual issues.

 

The best documentation I have ever seen is the 3dsmax guide. There is a tutorial section and there are materials and examples available for people wanting to get jiggy with the software, which unity has as well. I have no idea how much time and effort went into creating the 3dsmax resource, but I bet its a lot! Anyhow apart from that, I remember trying to understand the muscle section in mecanim and there was no info available, I google my ass off and hit the dox, no luck, also there were inconclusive posts and when I added my own they were not answered, which is cool, folks are busy or maybe nobody knew the answer. But these are basic things that need explaining and it would be great if you could just look the info up.

With the autodesk documentation you get the feeling the writer sat between an expert user and an inexperienced one to make the clearest text possible. Often people who write instructions are so familiar with the subject that they assume others know it too and information gets left out. Also while it is best to have a solid grounding in whatever aspect you are concentrating on, the way of working is not really always built on a stacked foundation. Often people will flick between scripting and publishing tests to shaders and animation in the space of a few hours which means the information needed is not read in sequence and should be capsules on their own if possible. The bottom of the max pages has a comment button for feedback, in fact autodesk likes feedback on its help files.

I'd just like to add that I am aware of what a mammoth and never ending task writing and providing documentation is so respect to those that do it.

 

It will be non-existant, actually. On modern CPUs, all basic math operations are the same speed. Even square roots are hardware operations and not particularly slow anymore. So this sort of thing doesn't belong in the docs, since it's outdated. You joke about the profiler, but that really is the best thing to do, because it's the only way you can be sure you're getting accurate info.

--Eric

 

I got that example from the old 2D Game engine I used:
Half way down you will see Math Performance.
https://docs.coronalabs.com/guide/basics/optimization/index.html

I will also posted what they said:
Math Performance
Certain mathematical functions and processes are faster than others. For example, multiplication is faster than division and you should multiply by a decimal instead of dividing.

--MULTIPLICATION BY DECIMAL (RECOMMENDED)
x * 0.5 ; y * 0.125

--DIVISION (DISCOURAGED)
x/2 ; y/8

Obviously I do not know Unity enough to know if this applies to Unity game engine or not, it was just a random example off the top of my head showing code examples from recommended route from the discouraged route. But I will admit the profiler is a very useful tool!

 

Honestly though, this has nothing to do with Unity and everything to do with general programming knowledge.
It doesn't warrant a place in Unity's documentation. It's also pretty unimportant just in general, too.

 

I'm going to go one step further and propose such micro optimisations would actually make the docs worse. In today's environment readable and supportable code is better then shaving off a couple of CPU cycles.

 

My head hurts thinking about the sheer mass of 'Optimise my microscopic code' questions I'd suddenly have to reject at UA. It'd actually be worth the time creating a USB Big Red Button I can strap to my monitor that when mashed rejects questions with the comment "Don't be ridiculous".

Please, lets not encourage it. I think I feel a bit of brain running down my left side-burn.

 

I fully agree with the OP. Navmesh part of documentation is missing a lot.