Improve Your Unity Asset Usability With Samples

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 Azure or custom server: git+https://[e-mail]/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, sample 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"
        }
    ],

As this is a json list, you can create several samples. Refer to full documentation. Some documentation is still worth reading 😉.

How to Create Good Sample ?

• Sample should contain a scene and should work out of the box when user loads the scene.
• Sample should be minimal, and focus on a single feature.
• If your package offer several features, create several samples.
• Sample should be small. Ideally, a single scene with a single node and a single script containing no more than a dozen line of code.

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.