Announcement

Collapse
No announcement yet.

Make API Reference Great Again!

Collapse
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

    Make API Reference Great Again!

    TL;DR: Proposition - change API Reference to Wiki style, with option to edit by all users.


    Unreal Engine API reference is... not bad, comparing to some automatically generated (PCL automatically generated documentation, for example), but it's far from being beginners friendly. We all know Disclaimer at the beginning of reference:

    The API reference is an early work in progress, and some information may be missing or out of date.

    Some modules are poorly described (like infamous Procedural Mesh Component), some of them are non-existent (like some functions from Editor.h)! I know that developing engine itself is a giant task - therefore, my proposition is to leave Documentation to community, and transfer it's content to editable WikiMedia system, like other sections (vide Tutorials).

    Let's look for Unity Scripting API reference:



    Very good for eye, examples in text. Long list of classes. Every link in text leads to another example. I know, it needs a lot of work to build such good text structure. I am proposing actually less work for moderators and Epic's hired specialists. Web design is less important when content is satisfying.

    Ah, last thing - if I made a mistake and re-posted actual proposition from month ago, please tell here what was moderators response.
    Attached Files

    #2
    This is a neat idea as I am still learning the internals... But, wouldn't we need some sort of approval system before posting? I mean, what if the content is poorly described or even incorrect? What would be really cool is to have a committee that would oversee the documentation process. Maybe Epic can give that team free passes to GDC or something cool?

    teak
    "A little bit of nonsense now and then is cherished by the wisest men..."
    -- Willy Wonka

    Smooth Zoom Camera Plugin for 4.24 here.

    Comment


      #3
      What i have always wondered, is why do we not have source control for documentation ? Community members could submit pull requests, staff could review and publish. I'm sure if there were a style guide many people would contribute, to the official docs
      Youtube
      Machine Learning C++ Plugin
      Lindenmayer System C++ Plugin

      Comment


        #4
        Originally posted by SaxonRah View Post
        What i have always wondered, is why do we not have source control for documentation ? Community members could submit pull requests, staff could review and publish. I'm sure if there were a style guide many people would contribute, to the official docs
        Would be great!

        Comment


          #5
          Originally posted by Ch3shireCat View Post
          Some modules are poorly described (like infamous Procedural Mesh Component)
          Well, you don't really need documentation any more for that since it's outdated now and this should be used instead

          https://forums.unrealengine.com/show...nerated-meshes!
          Easy to use UMG Mini Map on the UE4 Marketplace.
          Forum thread: https://forums.unrealengine.com/show...-Plug-and-Play

          Comment


            #6
            Originally posted by Ch3shireCat View Post
            TL;DR: Proposition - change API Reference to Wiki style, with option to edit by all users.


            Unreal Engine API reference is... not bad, comparing to some automatically generated (PCL automatically generated documentation, for example), but it's far from being beginners friendly. We all know Disclaimer at the beginning of reference:

            The API reference is an early work in progress, and some information may be missing or out of date.

            Some modules are poorly described (like infamous Procedural Mesh Component), some of them are non-existent (like some functions from Editor.h)! I know that developing engine itself is a giant task - therefore, my proposition is to leave Documentation to community, and transfer it's content to editable WikiMedia system, like other sections (vide Tutorials).

            Let's look for Unity Scripting API reference:

            [ATTACH=CONFIG]116541[/ATTACH]

            Very good for eye, examples in text. Long list of classes. Every link in text leads to another example. I know, it needs a lot of work to build such good text structure. I am proposing actually less work for moderators and Epic's hired specialists. Web design is less important when content is satisfying.

            Ah, last thing - if I made a mistake and re-posted actual proposition from month ago, please tell here what was moderators response.
            We know the API reference needs some love. More example code is one of the top things on the list of improvements there. We probably won't be moving it to a wiki and opening it up to the community in that way, but we do want to provide a way for the community to make contributions. The most likely method of doing so would be to allow comments on the API reference pages, similar to how the PHP documentation works. The current API reference is auto-generated from the source code comments, so theoretically the community can help update it by making pull requests through GitHub. We hope to provide a much better way of making contributions than pull requests, though.

            Originally posted by SaxonRah View Post
            What i have always wondered, is why do we not have source control for documentation ? Community members could submit pull requests, staff could review and publish. I'm sure if there were a style guide many people would contribute, to the official docs
            The source for the feature documentation is in GitHub and we do receive pull requests for it from time to time. As I mentioned above, the API reference is generated from the comments in the source code, which is also in GitHub, so you can submit pull requests for updates to that as well. We review all of those.
            Unreal Engine Documentation
            Bored? Follow me! @ffejnosliw

            Comment


              #7
              What Mr. Sweeny should do is build a wall around the cubicle section where the documentation people sit, while they are at work, so that they cannot leave. Thus, they will become more proactive in bashing those keys!

              (sorry, I had to!)
              WIP: Science Project - A collection of middle school through advanced college level science theory and formula-based functions for use in your own projects
              World Machine to UE4 Export Macro
              WM Folder Generator - Creates a folder that you name with HeightMap, NormalMap, SplatMap, and Tile sub-folders

              Comment

              Working...
              X