clean up prefab docs and add known issues section

Author: vkovec

com.unity.formats.fbx/Documentation~/TableOfContents.md

@@ -5,4 +5,5 @@
 * [Integrating Unity with 3D modeling software](integration)
 * [Setting FBX Export options](options)
 * [Developer's guide](devguide)
-* [Troubleshooting](troubleshooting)
+* [Troubleshooting](troubleshooting)
+* [Known Issues](knownissues)

com.unity.formats.fbx/Documentation~/knownissues.md

@@ -0,0 +1,9 @@
+# Known Issues
+
+* The FBX Exporter package does not support exporting `.asset` files.
+
+* Bind pose of animated skinned mesh is lost on export. For example, if you export an animated skinned mesh from Unity and import it into Autodesk® Maya® and Autodesk® Maya LT™ you will not be able to set the character into the bind pose using the **Rigging** > **Skin** > **Go to Bind Pose** command.
+
+* Name or path changes are ignored when converting a Model instance
+
+* Exporting animation only for animated lights and cameras is not currently supported

com.unity.formats.fbx/Documentation~/nested-prefabs.md

@@ -6,7 +6,7 @@ When a user imports a Model from a 3D modeling application such as Autodesk® Ma
 
 You can add components to a Model Prefab in the Scene, such as a collider. However, you cannot apply any change back to the Asset without breaking the link. In this way, a Model Prefab is a *read-only* Prefab, because it is non-editable except for overrides in the Scene.
 
-Using FBX Linked Prefabs is the best way to ensure that your Models continue to reflect any changes you make to your FBX files in external applications while still taking full advantage of the Prefab system. For example, while Linked Prefabs previously required the extra **FbxPrefab** component, the new FBX Linked Prefabs use only the Unity Prefab features. And you can create Variants of your Variants which all receive updates from the Model Prefab but provide a lot of flexibility. 
+Using FBX Linked Prefabs is the best way to ensure that your Models continue to reflect any changes you make to your FBX files in external applications while still taking full advantage of the Prefab system. For example, while Linked Prefabs previously required the extra **FbxPrefab** component, the new FBX Linked Prefabs use only the Unity Prefab features. And you can create Variants of your FBX Linked Prefabs which all receive updates from the Model Prefab but provide a lot of flexibility. 
 
 In addition, Variants give you some additional control over receiving updates from external applications. For example, if you have a Model with a Spot Light of size 10 and you override the size to 1 in your Variant, when the size and color change in the FBX file, the color will change but the size will remain 1.
 
@@ -77,26 +77,22 @@ When converting to an FBX Linked Prefab, the following window opens, displaying
 | __Source__                | Transfer the transform animation from this object to the __Destination__ transform.<br/><br/>**Notes:**<br/> - __Source__ must be an ancestor of __Destination__.<br/> - __Source__ may be an ancestor of the selected object. |
 | __Destination__           | Which object to transfer the transform animation to.<br/><br/>This object receives the transform animation on objects between __Source__ and __Destination__ as well as the animation on the __Source__ itself. |
 | __Export Format__         | Select the format for the FBX Exporter to use when exporting the FBX file (ASCII or binary). |
-| __Include__               | __Convert to FBX Linked Prefab...__ always exports both Models and Animation in the hierarchy. |
-| __LOD level__             | __Convert to FBX Linked Prefab...__ always exports All levels of detail (LOD) available in the hierarchy for LOD groups. |
-| __Object(s) Position__    | __Convert to FBX Linked Prefab...__ always resets the root object's transform during export. However, the Prefab maintains the global transform for the root object. |
+| __Include__               | __Convert to FBX Linked Prefab__ always exports both Models and Animation in the hierarchy. |
+| __LOD level__             | __Convert to FBX Linked Prefab__ always exports All levels of detail (LOD) available in the hierarchy for LOD groups. |
+| __Object(s) Position__    | __Convert to FBX Linked Prefab__ always resets the root object's transform during export. However, the Prefab maintains the global transform for the root object. |
 | __Animated Skinned Mesh__ | Check this option to export animation on objects with skinned meshes.<br/><br/>If unchecked, the FBX Exporter does not export animation on skinned meshes. |
 | __Compatible Naming__     | Check this option to control renaming the GameObject and Materials during export. <br/><br/>The FBX Exporter ensures compatible naming with Autodesk® Maya® and Autodesk® Maya LT™ to avoid unexpected name changes between Unity and Autodesk® Maya® and Autodesk® Maya LT™. During export the FBX Exporter replaces characters in Unity names as follows:<br/> - Replaces invalid characters with underscores ("\_"). Invalid characters are all non-alphanumeric characters, except for colon (":").<br/> - Adds an underscore ("\_") to names that begin with a number. - Replaces diacritics. For example, replaces "é" with “e”.<br/><br/>**Note:** If you have a Material with a space in its name, the space is replaced with an underscore ("_"). This results in a new Material being created when it is imported. For example, the Material named "Default Material" is exported as "Default_Material" and is created as a new Material when it is imported. If you want the exported Material to match an existing Material in the scene, you must manually rename the Material before exporting. |
-| __Don't ask me again__    | Check this option to use the same **Convert Option** properties and hide this window when converting to Linked Prefabs in the future. You can reset this option by turning on the **Show Convert UI** option under **Edit** > **Project Settings** > **Fbx Export** in Unity's top menu. |
+| __Don't ask me again__    | Check this option to use the same **Convert Option** properties and hide this window when converting to FBX Linked Prefabs in the future. You can reset this option by turning on the **Show Convert UI** option under **Edit** > **Project Settings** > **Fbx Export** in Unity's top menu. |
 
 > ***Note:*** For FBX Model filenames, the FBX Exporter ensures that names do not contain invalid characters for the file system. The set of invalid characters may differ between file systems.
 
-## Known issues
-
-* Name or path changes are ignored when converting a Model instance.
-
 <a name="conversion"></a>
 
-## Converting from Linked Prefabs to Prefab Variants
+## Converting from Linked Prefabs to FBX Linked Prefabs
 
-To convert existing Linked Prefabs to Prefab Variants, follow these steps:
+To convert existing Linked Prefabs to FBX Linked Prefabs, follow these steps:
 
-1. Fix any name discrepancies that were previously handled by the [name remapping functionality for Linked Prefabs](prefabs.md#Remapping) before converting. Prefab Variants do not handle name remapping. If you start to add game logic to components, and then the objects in the FBX get renamed, you are at risk of losing the components. This can happen because the old GameObjects are deleted and new objects with the new names are added in their place.
+1. Fix any name discrepancies that were previously handled by the name remapping functionality for Linked Prefabs before converting. FBX Linked Prefabs do not handle name remapping. If you start to add game logic to components, and then the objects in the FBX get renamed, you are at risk of losing the components. This can happen because the old GameObjects are deleted and new objects with the new names are added in their place.
 
 2. Right-click the Linked Prefab file and select **Convert to FBX Linked Prefab...** from the context menu.
 

com.unity.formats.fbx/Documentation~/prefabs-overview.md

@@ -3,13 +3,9 @@
 In version 2018.3, Unity introduced a new way of working with Prefabs: [Nested Prefabs](https://docs.unity3d.com/2018.3/Documentation/Manual/NestedPrefabs.html) allow you to create Prefabs inside other Prefabs, and [Prefab Variants](https://docs.unity3d.com/2018.3/Documentation/Manual/PrefabVariants.html) allow you to save a variation on an existing Prefab. However, this changes the way you work with the FBX Exporter, because you can no longer use *Linked Prefabs* to maintain a connection between Unity and your 3D modeling application. 
 
 Previously, Linked Prefabs were created by adding an FbxPrefab component to a Regular Prefab in order to connect it to an FBX file. 
-From Unity 2018.3 onwards, FBX Linked Prefabs will instead be created as Prefab Variants of the exported FBX file.
+From Unity 2018.3 onwards, FBX Linked Prefabs will instead be created as Prefab Variants of the exported FBX's Model Prefab.
 
-When you open an FBX file in Unity, the FBX Importer creates a Model Prefab. Model Prefabs are read-only, but you can create a *Prefab Variant* of that Model Prefab. 
-Prefab Variants are Prefabs which inherit all data from a base Prefab. Prefab Variants can create inheritance between ordinary Prefabs. 
-For example, you can create a Variant of a button Prefab which has a different color but the same functionality. 
-
-Since Prefab Variants allow you to override its base Prefab's properties, you can use a Prefab Variant of a Model Prefab to add components, Materials, or change most other property values without affecting the original FBX file.
+Since Prefab Variants allow you to override its base Prefab's properties, you can use an FBX Linked Prefab to add components, Materials, or change most other property values without affecting the original FBX file.
 
 > ***Note:*** While this method allows you to override properties, you cannot change the internal hierarchy of the Variant without breaking the link to the Model Prefab.
 
@@ -20,15 +16,14 @@ This type of connection is easy to maintain.
 
 ## Terminology
 
-* Model Prefab: Generated on import of an FBX file. A Model Prefab is a read-only representation of the FBX contents, which updates when the FBX file is modified.
+* __Model Prefab__: When you open an FBX file in Unity, the FBX Importer creates a Model Prefab. A Model Prefab is a read-only representation of the FBX contents, which updates when the FBX file is modified.
 
-* Prefab Variant: A Prefab generated from another Prefab (either Regular, Model, or from another Variant). It will inherit all data from the base Prefab, allowing additional modifications without affecting the base.
-                  For example, you can create a Variant of a button Prefab which has a different color but otherwise the same functionality.
+* __Prefab Variant__: Prefab Variants are Prefabs which inherit all data from a base Prefab. Prefab Variants can create inheritance between ordinary Prefabs. For example, you can create a Variant of a button Prefab which has a different color but the same functionality. 
 
-* Linked Prefab: A Regular Prefab containing an FbxPrefab component which connects to an FBX file. 
+* __Linked Prefab__: A Regular Prefab containing an FbxPrefab component which connects to an FBX file. 
                  The Prefab updates automatically when the FBX file is modified. Components are maintained and if object names or hierarchies change in the FBX file,
                  it is possible to remap the objects by name on import.
                  This is specific to previous versions of the FBX exporter, and requires Unity 2018.2 or lower.
 
-* FBX Linked Prefab: A Prefab Variant with a Model Prefab as its base. This feature replaces Linked Prefabs in Unity 2018.3 and above.
+* __FBX Linked Prefab__: A Prefab Variant with a Model Prefab as its base. This feature replaces Linked Prefabs in Unity 2018.3 and above.
                      A special component is no longer required, as FBX Linked Prefabs use only the Unity Prefab features.

com.unity.formats.fbx/Documentation~/troubleshooting.md

@@ -1,30 +1,11 @@
 # Troubleshooting
 
-## Known issues
-
 * When installing a new version of the FBX Exporter package after using version 1.3.0f1 or earlier, the link between Assets and FbxPrefab components may be lost. See [Updating from 1.3.0f1 or earlier](#Repairs_1_3_0f_1) for repairing instructions.
 
-* The FBX Exporter package does not support exporting `.asset` files.
-
-## Known issues
-
-* Bind pose of animated skinned mesh is lost on export. For example, if you export an animated skinned mesh from Unity and import it into Autodesk® Maya® and Autodesk® Maya LT™ you will not be able to set the character into the bind pose using the **Rigging** > **Skin** > **Go to Bind Pose** command.
-
 * Animated skinned meshes may not export with the correct skinning if they are not in the bind pose on export (that is, not being previewed in the Animation or Timeline windows, and the original Rig's FBX must not contain animation)
 
 * For skinned meshes all bones must be descendants of the root bone. For example, if the root bone is "hips" and the right leg for the same skinned mesh is not a descendant of hips, export will fail.
 
-## Known issues
-
-* Name or path changes are ignored when converting a Model instance
-
-## Known issues
-
-* Exporting animation only for animated lights and cameras is not currently supported
-
-
-----
-
 * Converting hierarchies with UI components will break UI
     * FIX: prepare hierarchy so that it has no UI elements before converting then add it back afterwards