Feedback on the new docs site

Clothing Tool | Unreal Engine Documentation

The video that’s supposed to play in Step 4 of Painting on your Cloth, gives out an error saying: No source video was found.

Hello, all. Although I am experienced in a couple of other engines, I am very new to Unreal Engine. Technical analyses and other engineering documents, often over 100 pages in length, have been a large part of my job for more than 20 years, so I appreciate the effort required to design, write, edit, and most of all, maintain, documentation. Over the past several several weeks I have spent many hours in the Unreal online documentation, so I wanted to share some constructive (and mostly positive) feedback with the documentation team.

Notwithstanding my usual desire to carefully organize, the points below are in no particular order. I assume that if the team chooses to act on any suggestion here, it would be split out into a task in Jira or Bugzilla or whatever tool the docs team uses.

  • The quality and depth of the documentation is exceptional for the software industry at large. Topics are presented in depth and with extensive screen captures and example walkthroughs, allowing learners to perform the steps in the editor. For experiential learners such as myself, this is a tremendous benefit.
  • Unlike so many companies in recent years, you clearly care about editing and proofreading. I am a notorious “grammar cop” in my small company, and I subconsciously proofread even when I am simply trying to absorb content. Yet I have found few grammatical or spelling errors in this documentation.
  • The balance between theory and practice seems well-chosen in most areas, although the best balance point will vary because every reader’s mind works differently, and every reader has a different learning objective. Theory is important to assimilate and generalize the specific examples to one’s own project, but too much theory can overwhelm newcomers.
  • I appreciate the banner at the beginning of many sections indicating the version of Unreal to which that section applies. One small suggestion would be to add text to those banners identifying whether that is the release for which the documentation was written or updated, or if that is the first release that contained this feature. Since the banners seem to be all formatted identically, I presume this would be just a constant text label from a template. A short phrase such as “Updated for 4.22” or “Feature added in 4.22”, for example, would suffice.
  • The tree-oriented menus work extremely well, but it would be nice if these could be more dynamically related to the content pane, in JavaScript-enabled browsers. The need for a full page refresh to select a different topic makes it cumbersome to jump back and forth. For instance, while reading about ABC there might be a mention of TUV, and the reader wants to look quickly at that and then return. This is possible in the existing ToC template, but it is a little inconvenient. Perhaps the user profile settings could offer a choice of modes for menu behavior, since the existing method may work better with the “back” button in some browsers.
  • If it is feasible, and if it would not create a maintenance nightmare, some additional menu depth might be helpful for certain topics where the finest-grained menu entry still links to one extremely long page.
  • Occasionally the game-centric focus of the documentation (admittedly, appropriate for many or most readers) seems to downplay aspects that are vitally important to non-game developers (of which I am one). For example, the Cloth simulation section covers only clothing and assumes one is painting cloth properties onto an existing garment mesh that is part of a character model. Of course this would apply equally to draperies in an archviz scene, and it’s not difficult to make that leap. However, that section was less helpful to me because I wanted to learn how to create a simple mesh using primitives or brushes in Unreal and then add cloth physics – for example, making a flag or banner from a plane. The information is present, but this workflow isn’t specifically covered.
  • The tutorial on learning Unreal from a Unity background is excellent and directly relevant to my journey. I would like to suggest that the team update the specific section “UE4 Blueprint Classes Can Be Extended” to reflect recent improvements in Unity. Unity now does support nested Prefabs (quite well, actually), and Prefab Variants negate the cumbersome workflow described in this section. (I am not saying the section is unfair; it simply does not reflect the latest Unity features.)
  • Unity developers can use an inheritance-based design pattern, or a compositional pattern, or a combination of both. It would be useful to explain which of these is preferred in Unreal, or if they are often combined, how (in broad terms) a Unreal developer might wish to choose the right pattern for common situations.
  • Also in the Unity to Unreal tutorial, it would be helpful to explain if the Scene Components nested under an Actor’s Root Scene Component can also be the Scene Components that are part of other Actors. This seems to be implied but is not explicitly stated or negated.
  • Once again in the Unity to Unreal tutorial, please consider mentioning the performance impact of Material Instances as compared to Unity’s Materials. In Unity, each Material added to a Scene requires a separate GPU draw call, whereas Material Property Blocks allow one Material to be multiply GPU instanced within a single draw call. It would be helpful to learn, early on, the “best practices” in Unreal for how freely to use Material Instances within a level.
  • There is a sentence fragment in the last paragraph of “Writing Event Functions” in the Unity to UE4 tutorial. The fragment begins with “Where as” (which should also be “Whereas”).
  • An important topic for Unity to Unreal migration is the behavior of the Editor if files in the Content directory tree are modified, added, renamed, moved, or deleted from the operating system’s file manager or an external creative tool. How does Unreal resemble or differ from Unity in this regard?
  • I haven’t yet found any official documentation on using external editing tools with specific asset or file types. Notably, I would like to use JetBrains Rider for source editing, even if Visual Studio is needed for compiling C++. It’s not reasonable to expect Epic to document specific external tools, of course, but it would be helpful if there was generic information about how external tools can be invoked by default from the Content Browser.
  • Offering both topic-oriented links from “Understanding the Basics” and role-centric links from “Getting Started in UE4” is a fantastic choice of learning paths for newcomers. Well done!

I hope it’s not out of line to offer this many comments as a relative newcomer. My intention is to bring the newcomer’s perspective, specifically, which is why I have refrained from offering half-baked remarks about the deeper technical aspects of this excellent documentation resource.

Once again, thanks to the Unreal documentation team, and the community members whose feedback has helped refine their work, for crafting superb documentation that is both approachable for novices and comprehensive for experts.

1 Like

Hello syscrusher,

Thank you for providing us a comprehensive and organized post on your constructive criticisms and praise. I’ve shared this with the members of our Documentation Team, and we have begun to internally log our Jira regarding some of the typo fixes and additional page information requests.

We hope to continue to improve our pages in conjunction with evaluating the valuable feedback provided by you and our other members of the Unreal Community.

Thank you!

1 Like

Hi ShinraCorp, we have a fix for the missing video issue, it’s going to be published as soon as we finish checking it.

1 Like

[Page URL]Find | Unreal Engine Documentation
[Description]Just now encounter with a small misleading demo picture in the docu. of the ‘FIND’ node of BP. The two different output pin node shares the same picture in which a yellow circle focusing on the same pin.

Get Started with UE4 - Editor Basics Section

A small typo here:

Blockquote The .uproject file is how you create, open, or save a project. You can create any number of different rojects and work on them in parallel.

1 Like

Hi msdfal63, thanks for the feedback! You are correct, the image was an error. The right image was already in the database, just needed to swap it in.

Hi DominikKowalczyk, thanks for spotting that. I fixed it immediately.

Here’s an occurrence in Opera GX LVL2 (core: 73.0.3856.438)

Monitor resolution is, again, 2560x1600. Out of that, the web browser window is 1279x1559. The content area is 1237x1478
In this case, re-loading the page actually did fix the issue. However, opening a new docs page in a new tab reproduced the issue. Opening subsequent pages in new tabs did not reproduce the issue.
(This really is an inconsistent one)
If you have any instructions for what you want me to do when it happens to collect info or whatever, I’ll gladly try it and get back to you.

Thanks, @DocMont. I could ask nothing more than that you’re listening. :+1:

As I’ve continued to use the docs, I’ve run across a couple of other topics that were unclear to me, so I’ll pass those along here.

World Composition

In the section on World Composition, I struggled for many hours with trying to add sublevels after I had my persistent level created and showing in the Levels window. I kept trying to reproduce the steps in the documentation and in several online video tutorials (both official and community-made). Nothing seemed to work. I had very carefully made sure the persistent level had no existing sublevels because of the warning the editor gives when first enabling World Composition. I would drop another existing level into the Levels window, or onto the persistent level, but never got it to add as a sublevel.

Finally I learned by accident what I had been missing, and what I think should be added to the docs: Sublevels need to be in the same directory as their parent level, or in a descendant under that directory. As far as I can tell, that’s not mentioned in the docs, and the online tutorials seem to take it for granted that everyone knows this. The warning from the editor is what threw me – I had intentionally put my intended sublevels in different directories because I interpreted the warning as “don’t have anything around that can confuse the initial World Composition setup; instead, set up a single level and then use the Levels window to add the others later, as in the tutorials.”

The effect of dropping a Level onto the current persistent level in the Levels window is not obvious from experimenting in the editor, so it may be worth describing that behavior in the docs as well.

Now that I have figured this out, it all makes perfect sense, of course. :smiley: This fits the old adage that “It’s easier to understand the documentation after you’ve learned the software.”

Origin Rebasing

The topic of origin rebasing is familiar to me from other engines, and I understand the floating point precision issue’s causes and effects, and also why we can’t simply use double-precision floating point to make it all go away. I don’t know how to implement this in Unreal Engine, however. It’s mentioned in the documentation, but seemingly only in passing. That’s sad because Unreal appears to be way ahead of most other engines in this feature – something that is hard to do in many engines but very well-supported in Unreal.

I recognize that documentation is always a work-in-progress and never finished, so I’m not upset that a niche topic like this isn’t covered in detail yet. Please simply count my feedback as one asking for this task to be on the to-do list in the near term.

Unreal World Coordinates

The section defining and comparing coordinate systems (local, world, texture, etc.) is extremely useful and something that would have been very easy to take for granted. The one very small addition I would recommend is to explain the customary use of the Cartesian axes in Unreal, with respect to object directionality and cardinal directions.

It’s fairly obvious that +Z is “up” and -Z is “down”, but please consider defining the conventions for “left”, “right”, “forward”, and “backward”. Also, when making landscapes, which axis is traditionally used as “north”?

The concepts of right-handed and left-handed coordinate systems might be worth mentioning as well, since that can profoundly impact import of 3D models.

As before, thanks for listening. I realize at least some of what I’ve suggested here would be a significant effort, but hopefully there are also some easy wins as well.

Have a great day!

In the first paragraph of the world composition documentation, while it doesn’t explicitly say “all sublevels need to be in the same folder as the persistent level”, it does say it scans the folder of the persistent level to find all other levels:

The persistent level does not store any streaming information and instead scans a folder and treats all found levels as streaming levels. Each streaming level has information stored in the package header, which World Composition can read without loading the level into memory.