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:
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.
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.
I think that’s a patently unfair thing to say, because I think the documentation has overall improved in quality in 4.5. You’re really talking about one specific problem, namely
and that’s fair enough, but picking out places where things got missed and then declaring that the whole thing’s gotten worse is not OK, IMO.
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.
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.
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.
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.