Improve Your Unity Asset Usability With Samples

Posted on Thu 01 June 2023 in misc

No one read the documentation.

It is the sad truth. You have developed the most awesome Unity asset, using the most advanced state of the art ray-casted-signed-distance-field-backed-layer-based-mipmap-inspired-linear-fading technic, but no-one understands how to use it. So you wrote a documentation. But people won't read it. Because no one read the documentation anymore.

If you want people to use your work, you have to make it easy to use.

Unity Package Layout

Unity recommends a specific folder layout for your package. It looks like this:

If you respect this layout, you can import your package in Unity using Unity's package manager Add package from disk or Add package from git URL if you store your sources on a git repository.

Try to import the Unity's High Precision Framework package:

  • Click on Add package from git URL...
  • past the git url: https://github.com/Unity-Technologies/com.unity.gis.high-precision-framework.git
    (for some reasons, you may have to add git+ if your git is stored on custom server:
    git+https://my-company@dev.azure.com/MyProject/_git/my-unity-package)

The package is importing. This may take a few minutes. You will notice the " View documentation" that no one ever click.

But a much more interesting part is the "Samples". This list samples provided in the package.

If you click on "Import" button, Samples will be downloaded and added to your Project Browser.

How to create samples for your custom package

Samples are stored in Samples~ folder of Unity Package Layout:

But to be present as Samples in Package Manager, you have to reference them in package.json:

"samples": [
        {
            "displayName": "High Precision Sample",
            "description": "Contains sample scene for the high precision framework",
            "path": "Samples~/SampleScene"
        }
    ],

How to create good sample

  • Sample should contains a scene and should work out of the box when user load the scene.
  • Sample should be minimal, and focus on a single feature
  • Sample should be small. Ideally, a single scene with a single node and a single script.

Conclusion

People prefer copy/past something they don't understand than understanding something to make it work. That's why they won't read the doc. So instead of spending time on documentation, prefer spending time on writing simple, self-contained examples.

Also, keep this in mind:

Not because you did something complicated means you did something smart

3D Unity