Search Unity

  1. Unity 6 Preview is now available. To find out what's new, have a look at our Unity 6 Preview blog post.
    Dismiss Notice
  2. Unity is excited to announce that we will be collaborating with TheXPlace for a summer game jam from June 13 - June 19. Learn more.
    Dismiss Notice

Documentation ideas

Discussion in 'Wish List' started by andeeeee, Aug 22, 2011.

  1. andeeeee

    andeeeee

    Joined:
    Jul 19, 2005
    Posts:
    8,768
    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!
     
  2. scarpelius

    scarpelius

    Joined:
    Aug 19, 2007
    Posts:
    966
    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.
     
  3. saymoo

    saymoo

    Joined:
    May 19, 2009
    Posts:
    850
    - 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.)
     
    Last edited: Aug 22, 2011
  4. Tiles

    Tiles

    Joined:
    Feb 5, 2010
    Posts:
    2,481
    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.
     
    Last edited by a moderator: Aug 22, 2011
  5. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
    - 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 ...."
    - ..
     
  6. Tiles

    Tiles

    Joined:
    Feb 5, 2010
    Posts:
    2,481
    Wow, everybody seems to be happy with the manual :/
     
  7. hippocoder

    hippocoder

    Digital Ape

    Joined:
    Apr 11, 2010
    Posts:
    29,723
    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.
     
    Last edited: Aug 23, 2011
  8. Eric5h5

    Eric5h5

    Volunteer Moderator Moderator

    Joined:
    Jul 19, 2006
    Posts:
    32,401
    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
     
  9. andeeeee

    andeeeee

    Joined:
    Jul 19, 2005
    Posts:
    8,768
    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.
     
  10. Tiles

    Tiles

    Joined:
    Feb 5, 2010
    Posts:
    2,481
    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.
     
    Last edited by a moderator: Aug 23, 2011
  11. hippocoder

    hippocoder

    Digital Ape

    Joined:
    Apr 11, 2010
    Posts:
    29,723
    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.
     
  12. mgear

    mgear

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

     
  13. andeeeee

    andeeeee

    Joined:
    Jul 19, 2005
    Posts:
    8,768
    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.
     
  14. scarpelius

    scarpelius

    Joined:
    Aug 19, 2007
    Posts:
    966
    GeSHI http://qbnz.com/highlighter/ for that, easy thing, though is a meticulous job to redo all the pages.
     
  15. Fidde

    Fidde

    Joined:
    Dec 20, 2010
    Posts:
    109
    +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.
     
  16. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
    - 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..)
     
  17. BIG-BUG

    BIG-BUG

    Joined:
    Mar 29, 2009
    Posts:
    457
    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
     
    Last edited: Sep 8, 2011
  18. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
    - 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)
     
  19. scarpelius

    scarpelius

    Joined:
    Aug 19, 2007
    Posts:
    966
    So, is there any resolution on this? Do you guys have a plan, have you take into consideration any proposition?
     
  20. cherub

    cherub

    Joined:
    Apr 26, 2006
    Posts:
    493
    smart search

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

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
    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..
     
  22. Mark-Sweeney

    Mark-Sweeney

    Joined:
    Feb 21, 2010
    Posts:
    172
    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?
     
  23. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
    Offline .chm help file would be nice to have also..
     
  24. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
    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
     
    Last edited: Dec 12, 2011
  25. Dreamora

    Dreamora

    Joined:
    Apr 5, 2008
    Posts:
    26,601
    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.
     
  26. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
    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)
     
  27. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
    (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")..
     
  28. Blejach90

    Blejach90

    Joined:
    Oct 3, 2011
    Posts:
    5
    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.
     
  29. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
  30. pangzi888

    pangzi888

    Joined:
    Mar 9, 2012
    Posts:
    1
    Good idea.
     
  31. suppenhuhn

    suppenhuhn

    Joined:
    Dec 15, 2011
    Posts:
    37
    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 ?
     
    Last edited: Mar 13, 2012
  32. nullstar

    nullstar

    Joined:
    Jul 2, 2010
    Posts:
    186
    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.
     
  33. Eric5h5

    Eric5h5

    Volunteer Moderator Moderator

    Joined:
    Jul 19, 2006
    Posts:
    32,401
    It's included when you download Unity.

    --Eric
     
  34. suppenhuhn

    suppenhuhn

    Joined:
    Dec 15, 2011
    Posts:
    37
    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
     
    Last edited: Mar 14, 2012
  35. ryungmin

    ryungmin

    Joined:
    Feb 19, 2008
    Posts:
    1
    1. User editable, like wiki
    2. Support each country page
     
  36. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
  37. YorickVanVliet

    YorickVanVliet

    Joined:
    Nov 14, 2009
    Posts:
    22
    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.
     
  38. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
    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..?
     
  39. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
  40. Hiren

    Hiren

    Joined:
    May 6, 2012
    Posts:
    2
    Hi for unity documentation can you guys how the documentation works..
    Like can you guys explain how functions work in unity
     
  41. Adam-Buckner

    Adam-Buckner

    Joined:
    Jun 27, 2007
    Posts:
    5,664
  42. MonoSapiens

    MonoSapiens

    Joined:
    Apr 12, 2012
    Posts:
    79
    More examples for C#
     
  43. Nuttygamer

    Nuttygamer

    Joined:
    Aug 12, 2012
    Posts:
    2
    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
     
    Last edited: Aug 14, 2012
  44. jwinn

    jwinn

    Joined:
    Sep 1, 2012
    Posts:
    88
  45. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
  46. superpig

    superpig

    Drink more water! Unity Technologies

    Joined:
    Jan 16, 2011
    Posts:
    4,660
  47. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
  48. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503
    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..
     
  49. Eric5h5

    Eric5h5

    Volunteer Moderator Moderator

    Joined:
    Jul 19, 2006
    Posts:
    32,401
    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
     
  50. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    9,503