Search Unity

The state of documentation

Discussion in 'Documentation' started by Romeno, Apr 6, 2019.

  1. Romeno

    Romeno

    Joined:
    Jun 24, 2013
    Posts:
    35
    I'm new to Unity and I really struggle to put together things from documentation. It seems all over the place and at the same time giving little cross references. It is often you find information you need on pages you dont think you find or should find it. And they pages that should have the information does not have it.

    I want to stress it. Cross-links are a definite problem. The bigger problem is that documentation is shallow. It looks like there is some source of information that is the bigger one. And as far as I can tell I found that place to be the Unity blog.

    I mean the documentation is not bad. You understand things if you read it. But you need to be not just attentive to read it. You need to search for info in this documentation. It looks like a heap of well organized info pieces. But it still a heap. And you need to search it and a lot of info is not were it needs to be.

    I read much more well put and like godly organized documentations. A lot of examples have errors, are outdated or contain references to obsolete objects. Like Django one is the best there. A lot of other open-source documentations are very reasonable. But this... I mean... It looks like the best we can get.

    Are the docs on github btw? This really looks awfull to me. I would prefer to issue pull requests for these docs than "rate" the articles and leave a "feedback". Well what about to feedback on my feedback?

    I don't know this really looks bad to me. Even MSDN and other huge corporate documentations are well maintained and well put. I know they have much more financial stability. Don't know if Unity does... Like small indie company. Everybody knows that... But...

    This really feels like sloppy attitude...
     
    Romeno, Apr 6, 2019
    #1

  2. JamieLanger

    JamieLanger

    Joined:
    Apr 10, 2019
    Posts:
    3
    + 1 here.
    Even I'm new to Unity and I really struggle to put together things from documentation. It seems all over the place and at the same time giving little cross references. It is often you find information you need on pages you dont think you find or should find it. And they pages that should have the information does not have it.
     
    JamieLanger, Apr 10, 2019
    #2

  3. Romeno

    Romeno

    Joined:
    Jun 24, 2013
    Posts:
    35
    The more I learn Unity the more I got fascinated how bad the documentation is. You need to experiment when learning this engine. Documentation is more of a reference. It's just a list of things that are there with little to no explanation to what it does and how it does it.
    I didn't happen to learn UnrealEngine, but is documentation there also bad?
     
    Romeno, Apr 15, 2019
    #3

  4. ronaledsmith

    ronaledsmith

    Joined:
    Apr 19, 2019
    Posts:
    6
    Nice to hear from your experiences. I'm also on the track to learning about Unity, Hope It would be helpful to me as well.
     
    ronaledsmith, Apr 19, 2019
    #4

  5. RexDaemon

    RexDaemon

    Joined:
    Apr 23, 2019
    Posts:
    1
    I thought it's not that bad actually...

    Do you have examples on a good written documentation, for me to compare, please?

    /thanksupfront
     
    RexDaemon, Apr 23, 2019
    #5

  6. ronaledsmith

    ronaledsmith

    Joined:
    Apr 19, 2019
    Posts:
    6
    Hey Romeno,
    It's appreciatable. Yes, documentation is not bad and you can also get it on GitHub.
     
    ronaledsmith, Apr 24, 2019
    #6

  7. paultan

    paultan

    Unity Technologies

    Joined:
    Oct 6, 2016
    Posts:
    5
    Hi All!

    Thanks for your feedback. Was your feedback about the main body of documentation on docs.unity3d.com for each Unity version or was it about some package documentation or both?

    We understand your frustrations and are always working on improving the content and user experience. While some package documentation may have source files and documentation on GitHub, we aim for all documentation to be served primarily from docs.unity3d.com

    Do let us know if you have specific comments on particular pages and we'll see what we can do in the short term as we work on long term improvements.

    Cheers!
     
    Last edited: May 10, 2019
    paultan, May 10, 2019
    #7

  8. siobhangibson

    siobhangibson

    Unity Technologies

    Joined:
    Mar 21, 2016
    Posts:
    8
    Hi folks,

    Like Paul, I also work on the documentation team. I wanted to respond as well because it's important to us that you know we're aware of these problems. Over the three years I've been on the team, strategic discussions have always been focused on how to handle the absolutely massive amount of content in the documentation, and how to manage maintaining existing content alongside producing new documentation for new features. To give you some context, Unity has been around for over ten years, and the documentation team has been around for 3-4 years - we have a lot of catching up to do, and it's something we're actively working on.

    We really appreciate feedback like this; it's proof that we're focusing on the right things. We have content audits and overhauls planned, but for obvious reasons, they take time and strategy to implement properly. In the meantime, as my colleague Paul said, the feedback form is a great way to report specific pages. When we come to improve a page, we pull all feedback notes on it to make sure we're prioritising the right issues, so it really helps.

    Thanks again!
     
    siobhangibson, May 10, 2019
    #8