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.