Search Unity

  1. Welcome to the Unity Forums! Please take the time to read our Code of Conduct to familiarize yourself with the forum rules and how to post constructively.
  2. We have updated the language to the Editor Terms based on feedback from our employees and community. Learn more.
    Dismiss Notice
New Forum User Notice Update to the Unity Editor Software Terms

Resolved Packages docs are still horrible

Discussion in 'Scripting Dev Blitz Day 2023 - Q&A' started by Baste, Feb 23, 2023.

  1. Baste

    Baste

    Joined:
    Jan 24, 2013
    Posts:
    6,204
    So we have been shouting this at you for years now, and nothing happens.

    Compare and contrast
    Scripting API docs for a package
    Scripting API docs for core Unity stuff

    The layout for the packages are just horrendous. What happened? Why did you go for the new, bad layout when you had a good one? Is this on the radar internally?

    There are some improvement - manual/scripting API for the same component on the same page so you can switch between them without going back to the front page, a changelog page, search that targets only that component. But I feel like the layout for the fields, methods etc. is so horrendously, obviously unreadable that it kills any goodwill for those small improvements.
     
    Baste, Feb 23, 2023
    #1
    steinbitglis, Ryiah and Trigve like this.

  2. xoofx

    xoofx

    Unity Technologies

    Joined:
    Nov 5, 2016
    Posts:
    412
    I can't tell in the details, because this topic is not owned by the .NET Group, but one reason I can think of that can explain this discrepancy is that we are using a fork of docfx for packages while the Unity doc is relying on a different old tooling. I believe it is on the radar but I don't know more about it, sorry.
     
    xoofx, Feb 23, 2023
    #2
    mariandev likes this.

  3. Baste

    Baste

    Joined:
    Jan 24, 2013
    Posts:
    6,204
    What I'm terrified of is that what's on the radar is replacing the "old tooling" (aka the actually good stuff) being replaced with the "new one" (aka. unreadable mess) everywhere.
     
    Baste, Feb 23, 2023
    #3
    Trigve and Saniell like this.

  4. xoofx

    xoofx

    Unity Technologies

    Joined:
    Nov 5, 2016
    Posts:
    412
    I think this is known at Unity and it is being worked out. We don't want to make the doc experience worse but better, so hopefully, this should improve. Sorry, can't give any more helpful details as I'm not involved directly on this topic. :)
     
    xoofx, Feb 23, 2023
    #4
    mariandev and Baste like this.

  5. RobJessop

    RobJessop

    Unity Technologies

    Joined:
    Mar 8, 2017
    Posts:
    2
    DocFX vs. in-house tooling as the reason why the two are currently different is correct.

    This is a bit before my time so is second hand, but I think the following is pretty accurate:
    The custom tooling for Unity's script reference has implementation details that arose from the way we used to author Unity's API. One crucial detail is that it was desirable to keep the documentation source files separate from the code. We created a format and custom tooling (using Unity) for this.

    Unity Package Manager packages are quite different products from Unity itself in terms of how they get compiled and distributed. We don't need our very Unity-specific tooling or format to author API for UPM packages, so the opportunity was there to adopt common, open formats and tooling for documenting API.

    We use vanilla DocFX and its memberpage plugin, but customize our own templates. Our API documentation generation is currently being reviewed and we don't have anything to announce at this time. Thanks for this feedback!
     
    RobJessop, Feb 23, 2023
    #5
    mariandev and xoofx like this.