Documentation ideas

The title says it all really. I'm starting this thread to discuss ideas for additions and overall improvements to Unity's documentation. Mistakes and outdated bits of the the docs are best reported with the standard bug reporter, but any other ideas would be welcome here (as long as they are polite, at least ;-)

Looking forward to hearing what you come up with!

 

I use the script reference quite a lot and what I would like to see is the ability to add comments like php have on their online function documentation. Something like this http://www.php.net/manual/en/function.file.php, you will see at the end of the page detailed pieces of code submitted by users.

 

- Some functions (in the reference) are not marked as PRO only, while they are:
http://unity3d.com/support/documentation/Components/index.html

- Some pages doe not contain the script language selection for the examples (viewing code as, Javascript, C#, Boo), while others do offer this.

- Although it's not about the manual, it's still about information presented:
The resource section need an update, so the samples/tutorials etc all do work nicely with the current release.

- Although it's not about the manual, it's still about information presented:
On the frontpage, you should make it more clear that features highlighted are PRO only, e.g. by marking them with the asterisk.
(and at the bottom of the page, stating this feature is PRO only.)

- The suggestion someone made (the document needs improvement thread in gossip), of placing guiding pictures to the text, i think is a very good suggestion. (some people learn/understand things better if it's guided visually. It also can clarify things better. Why do you think most books have some guided pictures included? and what about the success of 3dBuzz.)

 

What i`m still in trouble with is that the Docs provides me with the words, but not so much with the grammar and spelling and sentences. I am lost with 95% of the provided examples. When there are examples available at all. When the manual would be all i would have then i would have to give up.

As told in another thread already, a good example for that is the AudioClip. I can read that i can use a audio clip. And in the scripting reference i can read about variables like length and samples and volume. But there is not a single example that explains how i play an audioclip by script then. I had to dig in the Lerpz tutorial to find a working example. And am still unsure what is what, what comes where, and how to extend if needed.

I miss examples like

Code (csharp):

1.  
2. AudioSource.PlayClipAtPoint(SFXPlayerjumping, transform.position, 1);

and commented examples to explain what is going on. Like this one:

Code (csharp):

1. AudioSource.PlayClipAtPoint(Insert your clip here, Insert your position here, Insert your Volume here (Range goes from 0 to 1) );

PlayClipAtPoint does this. But there is no connection to Play Audio. When i search for a way to play an audio then i search for Play and Audio. And end with nothing really useful for me.

I also have to double scarpelius request. What would be great would be something like a comment system, at least for the online version. That way we could add lots of missing bits by the community.

Also nice to have would be some super simple example projects that are linked to the manual. Like how to rotate a cube. Or how to play a sample by clicking at a button. It`s those small things where you learn from.

 

- images (that show what the commands does ^^ as mentioned there also)
- more complete example sources (not just 1 line)
- multiple examples how to use it difference cases (if necessary)
- automatic "related posts"-links at the bottom (or if not automatic, someone could add links to posts that are helpful to this command)
- more shader info/tutorials/examples
- more tips from makers of unity (so people use the full capacity of the engine) (little box on the side: "ProTIP: for best performance assign this ...."
- ..

 

Wow, everybody seems to be happy with the manual :/

 

The most important thing IMHO is to link both sides of the documentation together. Currently it can be a pain to google or search and get to the docs regarding workflow, say skinned mesh, and not have a link to the script equivelent.

So putting a link both ways at the bottom of each command to the workflow editor docs and the editing version of the docs would allow people to quickly look up the code version.

Thats making existing docs more useful and powerful as opposed to just adding to them.


I feel thats what confuses newbies a lot: they "only" find the docs for the editor version of meshes or rigidbodies and don't realise there is a scripting version of the docs, which would help their understanding much more instead of us shouting at them to read the docs.

 

It's more good than bad. It already does what you're asking for in many/most cases, so I have to wonder if you're just misreading it. For example, your request:

This info is already listed, right at the top, in a more useful form. "Insert your position here" is vague and doesn't really tell you what you should use. "position : Vector3" tells you exactly what you need. The only thing missing is that it doesn't specifically say the range for the volume is 0..1. You can infer that from the default, but ideally it should say so just to be perfectly clear. The reference guide isn't going to teach you how to program, if that's what you're asking for...it's a reference guide.

What needs to be fixed is those pages that consist of one very brief cryptic line of text (or sometimes nothing at all) with no code example.

--Eric

 

Well, the component reference pages have a link in the top right corner saying "Switch to Scripting" (and the Script Ref pages have an equivalent link back to the component) which lets you quickly switch between script API and editor.

 

As told, i am lost with 95% of the examples. And have again and again to ask at the forum or search through other resources and tutorials at the internet. Does this really sound good?

Well, as told before, it is not really bad. But it is not good neither. It could be much better.

Let`s say i am unexperienced, and want to play an audiofile.

Search the docs for play audiofile: 0 search results

Search the docs for play audio file, 2 search results. Which both has nothing to do with what i want.

Search the docs for play and audio. Now it looks better. Then have a closer look at the search result. And then tell me, with just these results, how to play an audio file in Unity. You can`t. The vital infos are not in reach. What you find for example is :

AudioSource.Play
Plays the clip.

Oh, great, that`s what i want to do. I want to play my audio file. Then you click the link and find yourself at just the word audio.Play(); . Which helps you nothing really.

Search for play audio clip: 15 search results which leads you to nothing really useful.

Search for play audioclip: 10 search results which leads you to nothing really useful.

And that was it. Even after searching combinations of my keywords, there is not a single example or explanation of how to play an audiofile. There is no hint towards PlayClipAtPoint, no connection to play audio. Not in the scripting section, not in the Component section. And you can`t search for it neither, because you don`t even know it exists. I have no other choice than to ask at the forum or to dig in scripting examples outside of the manual.

And that was just one example. This traps me again and again. The manual does NOT what i ask for, unfortunately. I have to disagree, sorry

The problem is, when you are very experienced then it is clear where to find your infos. You know 90% of the tags already. And you can be sure that you have seen your needed tag for your current case before. But then you don`t need the manual anymore really. Then you are happy with what is available. But you need the manual most when you are not this experienced. And then the manual cannot be detailled enough.

This switch is a good thing. But it is not everywhere available. Array for example does not have a Component link. And i could bet that this posibility to switch between scripting and component is the number one overlooked feature.

 

Yep but not for that particular item, it just switches to the root of the other, instead of going from rigidbody reference to rigidbody scripting reference.

 

- scripting search could have autocomplete, and search suggestions, if you misspelled the word
- more colors ? function ToAngleAxis (out angle : float, out axis : Vector3) : void

 

No, it really does go to the right page (eg, from the Rigidbody script ref page to the Rigidbody component page). Underneath where it says "Manual - Reference - Scripting" at the top, you should find a link that says "Switch To Component" or "Switch To Reference" depending on what you are looking at. Unless you are falling foul of a problem, these links should take you to the right page.

 

GeSHI http://qbnz.com/highlighter/ for that, easy thing, though is a meticulous job to redo all the pages.

 

+1 vote for rated comment fields below the documentation to add and rate useful code snippets. Not unlike the PHP reference pages. Other than that, I like the docs.

 

- have link from local help pages to web version (many times i've help page opened and want to copy paste the link for someone, but its local page (file:///Ö:/Program Files (x86)/Unity/Editor/Data/Documentation), then need to go googling to get the real page link..
(or is there some option to always use web help?)

- have "copy to clipboard" somewhere around the source examples (saves you from having to select the whole source..)

 

As mentioned in the other thread a Shader Command Reference (incl. predefined macros, variables and compiler pragmas) would be really helpful. (incl. remarks if a specific command is not available on certain devices)
For each type of shader (Fragment, Vertex, Surface) there should be a description in table form which in- and output values are possible / obligatory
A differentiation between the possible techniques( fixed function, fragment, vertex, surface ) and when to use what and how interaction with Unity lights and Beast lightmaps works.
Better and more detailed description for Surface Shaders. How does multi-pass rendering work? Which of the regular shader commands like Blend, ZWrite, Lighting work? Is it possible to write a depth value? How to combine surface shader with regular ones? etc

 

- function list as separate frame? (like in many other help files, so you can scroll it around while main page stays,
and maybe sidemenu as a list? (start typing the 1st letter f and it jumps to functions starting with f.. similar to most .chm help files keyword search)

 

So, is there any resolution on this? Do you guys have a plan, have you take into consideration any proposition?

 

smart search

for example, when I search "Get" something should be returned.

 

Would be nice to have help pages for every command,
even for 'function', 'int', 'for', 'private'.. and all those..

The other day was searching the help, to see how to pass array as an function parameter, but:
Your search for "function" did not result in any matches,
then that means browsing through lots of forum topics to find some example code..

and related to this,
if the autocomplete was better, like in autoIT or visual express studios (it shows full info, parameters etc)
you wouldnt need to go search for help in most cases at all..

 

I'd love to see the documentation as a searchable pdf with links that take you to relevant sections. Instead of hundreds, or thousands of separate web pages, wouldn't one master document be easier to update and add new examples, tutorials etc to?

 

Offline .chm help file would be nice to have also..

 

Just testing ios publishing for the 1st time,

I think this page could use some images updates..
http://unity3d.com/support/documentation/Manual/iphone-accountsetup.html

most of the page layouts in dev center have changed and its not easy to look for:
"Download link is in the same "Certificates" just above "Important Notice" red text block. "

then,
"Provisioning Profiles are a bit complex, and should be set up differently depending on how you've organized your team."

Even then, how about giving some basic example?
(so unity users can get started easily, without reading all apple documents,
as in my case, i'd just like to make 1 test publish..)

Or make it as easy tutorial like this,
Learn how to set up your development environment to build iOS apps on Windows
http://www.gotoandlearn.com/play.php?id=133

 

Those documentations should actually be removed.
They are back from days before apple made the portal "beginner proof". Nowadays the wizard will carry you through it if you are new to the process.

Generally it makes no sense for unity to document it anyway as its not related to Unity but XCode and the SDK only and apple changes part aspects of it every now and then, changes how it works in XCode, when they feel like it so its relevant to understand the page and the related apple documentation.

 

oh i see..

I'd still be a happy customer if the support people/evangelist would make the effort
and compile that kind of videos for the beginners, even though 90% of it would be the xcode setup.
(and most likely they know the overal best settings etc, so I dont have to read a 200 page pdf from apple..)

ps. didnt manage to publish to ipad, I followed those instructions,
but ended up with some errors (and didnt have time to googleup)
(its mainly because that i've never used xcode or ipad with mac before..
but with that kind of video walkthrough it would had been possible)

 

(sorry, I keep posting here when I notice some missing info in the docs..as if it would be in the docs, it would save a lot of time..)

About shader documents:

this page says:
http://unity3d.com/support/documentation/Components/SL-ShaderPrograms.html

"It is possible to override these limits using #pragma profileoption directive. E.g. #pragma profileoption MaxTexIndirections=256 raises texture indirections limit to 256. "

Took sometime to google what other options are available (for example "NumTemps")..

 

It would be nice to have PDF version of documentation(to download). I tried to download and convert(to PDF) unity manual(printable version) and i had problem opening page(letters were small). Then i went to two of my friends(better CPU, faster connection), and I still had a problem with downloading that page.

 

I know its not yet a long time since the release,
but would be nice to have atleast 1 line as an example for the new commands..

for example here,
http://unity3d.com/support/documentation/ScriptReference/ParticleSystem.html

 

Good idea.

 

First of all:
The documention is great!

1. think that a search-function within the reference- and usermanual would be a good feature.
2. is it possible to get a "offline" documetation ?

 

The problem I see with the scripting documentation side is that it is clearly just auto-generated from the code using doxygen or some such which results in it being little more than a web search friendly version of the header files and nothing more. Therefore they really provide no more benefit than simply browsing through the headers or having a good look through your IDE's auto complete drop-downs other than being a bit more search friendly. I feel that the level of information suffers as a result since all you can really gain from these docs are lists of what each class contains and what the functions are called but little information on their correct or intended usage or how to format your inputs into these functions and how their outputs are structured. I feel that the scripting documentation would benefit greatly from a bit more of a personal touch.

 

It's included when you download Unity.

--Eric

 

Yes, sorry - i meant offline as a .chm - works better mobile devices. on mine ( galaxy 10.1 ) no pictures are shown and can't use the "previous page" function

 

1. User editable, like wiki
2. Support each country page

 

..why in firefox the ctrl+click doesnt open links in new tab anymore?

for example on this page it wont open..(in IE it works)
http://unity3d.com/support/documentation/ScriptReference/ParticleSystem.html

(ctrl+click works in other sites/pages with firefox..but not in the unity documents..Oo?)

 

Documentation in the XML format Visual Studio understands! Just like this, only then for Unity 3.5.
This really would make developing much easier, we'd just have documentation in our IDE itself.

 

any news of some progress in this topic..or what is coming up / planned?

today bumbed into 1 "helpful" document page: Touch.position

ok..um...position in screen? in the element? screencoords or ? examples? what..?

 

this is some old page?

http://unity3d.com/support/documentation/ScriptReference/RenderTexture.SetBorderColor.html

that command doesnt seem to work, and its not listed in the "RenderTexture" page..

 

Hi for unity documentation can you guys how the documentation works..
Like can you guys explain how functions work in unity

 

Hiren, I suggest that you take on of my online classes:
http://unity3d.com/support/online-training/

This will give you a good introduction into how Unity works.

Also search thru this section for a large number of tutorials you can take, which will help you with understanding how to code for Unity, including this thread:
http://forum.unity3d.com/threads/113937-Getting-Started-with-Coding-for-Unity

 

More examples for C#

 

More example code, all coding sections should have code in all languages that are programmable in Unity. Perhaps even help for GUI items, I still have no clue what layers are, and how to make them. Online version should have videos, even it covers several topics would also be nice.

Also, can start a community set of standards when it comes to making unity help videos, for example, naming conventions, and such. Sure I can go onto Google and look for videos on how to do things, but there isn't a naming conventions such as version it works with, language used. Sometimes, when making a video, make it a requirement that the upload must make the same video for all languages, just incase people aren't proficient in converting from one language to another

 

Mathf.Lerp needs a better explanation on the docs. This one is pretty good: http://answers.unity3d.com/questions/237294/how-the-heck-does-mathflerp-work.html

Bigger question; why can't the docs be in a user-edited wiki, or possibly commented upon like the PHP docs, if that is more possible?

 

This page doesnt have list of allowed axisnames..
for example this is missing: Input.GetAxis("Mouse ScrollWheel")

http://docs.unity3d.com/Documentation/ScriptReference/Input.GetAxis.html

 

Oh i see.. "Mouse ScrollWheel" is just a preset default name.

Then could add some line to say that axisNames are defined in,
http://docs.unity3d.com/Documentation/Manual/Input.html

 

How about,
if obsolete script functions would be still included in the docs? (but marked clearly as deprecated/obsolete..)

Because,
1. if you have some old script and it gives error "The name 'ThirdPersonController' does not denote a valid type ('not found'). Did you mean 'UnityEngine.ThreadPriority'?"
2. You press help for "ThirdPersonController"
3. Searching script docs doesnt help: "Your search for "ThirdPersonController" did not result in any matches. Please try again with a wider search "

Instead it should give you:
ThirdPersonController (obsolete)

And then on that page there would be info:
- on what version it was removed, what is the current method etc..

 

No, because ThirdPersonController is a script. It's not obsolete or anything, nor is it a Unity function; you simply don't have it included in your project.

--Eric

 

Thanks again!

After 4.1 update some pages are missing documentation?
example,
http://docs.unity3d.com/Documentation/ScriptReference/Vector3.Distance.html