Use this template to create preliminary, high-level documentation meant to introduce users to the feature and the sample files included in this package. When writing your documentation, do the following:
-
Follow instructions in italics.
-
Replace angle brackets with the appropriate text. For example, replace "<package name>" with the official name of the package.
-
Delete sections that do not apply to your package. For example, a package with sample files does not have a "Using <package_name>" section, so this section can be removed.
-
After documentation is completed, make sure you delete all instructions and examples in italic (including this preamble).
Name the heading of the first topic after the official name of the package. Check with your Product Manager to ensure that the package is named correctly.
This first topic includes a brief, high-level explanation of the package and, if applicable, provides links to Unity Manual topics.
There are two types of packages: a) packages that include features that augment the Unity Editor, or b) packages that include sample files. Choose one of the following introductory paragraphs that best fits the package:
a) Use the <package name> package to <list of the main uses for the package>. For example, use <package name> to create/generate/extend/capture <mention major use case, or a good example of what the package can be used for>. The <package name> package also includes <other relevant features or uses>.
or
b) The <package name> package includes examples of <name of asset type, model, prefabs, and/or other GameObjects in the package>. For more information, see <xref to topic in the Unity Manual>.
Examples (For reference. Do not include in the final documentation file):
a) Use the Unity Recorder package to capture and save in-game data. For example, use Unity Recorder to record an mp4 file during a game session. The Unity Recorder package also includes an interface for setting-up and triggering recording sessions.
b) The Timeline Examples package includes examples of Timeline assets, Timeline Instances, animation, GameObjects, and scripts that illustrate how to use Unity's Timeline. For more information, see Unity's Timeline in the Unity Manual. For licensing and usage, see Package Licensing.
This subtopic includes a bullet list with the compatible versions of Unity. This subtopic may also include additional requirements or recommendations for 3rd party software or hardware. An example includes a dependency on other packages. If you need to include references to non-Unity products, make sure you refer to these products correctly and that all references include the proper trademarks (tm or r)
This <package name> version <package version> is compatible with the following versions of the Unity Editor:
- 2017.2 and later (recommended)
- 2017.1
- 5.6
To use this package, you must have the following 3rd party products:
- <product name and version with trademark or registered trademark.>
- <product name and version with trademark or registered trademark.>
- <product name and version with trademark or registered trademark.>
This section lists the known limitations with this version of the package. If there are no known limitations, or if the limitations are trivial, exclude this section. An example is provided.
The <package name> version <package version> includes the following known limitations:
- <brief one-line description of first limitation.>
- <brief one-line description of second limitation.>
- <and so on>
Example (For reference. Do not include in the final documentation file):
The Unity Recorder version 1.0 has the following limitations:
- The Unity Recorder does not support sound.
- The Recorder window and Recorder properties are not available in standalone players.
- MP4 encoding is only available on Windows.
This section should always begin with a cross-reference to the official Unity Manual topic on how to install packages. If the package requires special installation instructions, include these steps in this section.
<The text and cross-reference is still to be determined. It will be added by the Documentation Team.>
Exactly what is included in this section depends on the type of package.
a) For packages that augment the Unity Editor with additional features, this section should include workflow and/or reference documentation:
- At a minimum, this section should include reference documentation that describes the windows, editors, and properties that the package adds to Unity. This reference documentation should include screen grabs (see how to add screens below), a list of settings, an explanation of what each setting does, and the default values of each setting.
- Ideally, this section should also include a workflow: a list of steps that the user can easily follow that demonstrates how to use the feature. This list of steps should include screen grabs (see how to add screens below) to better describe how to use the feature.
b) For packages that include sample files, this section may include detailed information on how the user can use these sample files in their projects and scenes. However, workflow diagrams or illustrations could be included if deemed appropriate.
c) For packages that add runtime functionality, this section may include detailed information on what runtime improvements the package adds to Unity. Since there is no customer facing UI, there is probably no need to add screen shots.
(This section is for reference. Do not include in the final documentation file) If the Using <package name> includes screen grabs or diagrams, a link to the image must be added to this MD file, before or after the paragraph with the instruction or description that references the image. In addition, a caption should be added to the image link that includes the name of the screen or diagram. All images must be PNG files with underscores for spaces. No animated GIFs. An example is included below:
Notice that the example screen shot is included in the images folder. All screen grabs and/or diagrams must be added and referenced from the images folder.
For more on the Unity documentation standards for creating and adding screen grabs, see this confluence page: https://confluence.hq.unity3d.com/pages/viewpage.action?pageId=13500715
This section includes the revision history of the document. The revision history tracks when a document is created, edited, and updated. If you create or update a document, you must add a new row describing the revision. The Documentation Team also uses this table to track when a document is edited and its editing level. An example is provided:
| Date | Reason |
|---|---|
| Sept 12, 2017 | Unedited. Published to package. |
| Sept 10, 2017 | Document updated for package version 1.1.New features: |
| Sept 5, 2017 | Limited edit by Documentation Team. Published to package. |
| Aug 25, 2017 | Document created. Matches package version 1.0. |