Improve Your Unity Asset Usability With Samples
Tags: unity3d
Published: 2023-06-02 07:39:14

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](https://docs.unity3d.com/Manual/cus-layout.html) for your package. It looks like this:


![Unity folder layout](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/waoabqkl4ltdlx4hwwcd.png)

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.


![Unity package manager](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/u80h84uvtqgem5r02hbw.png)


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://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.

![Package documentation link](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/exwev44tyy8jb23tbi5x.png)

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

![Package samples](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/czk39phkwodfj20c2smo.png)

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](https://docs.unity3d.com/Manual/cus-layout.html):


![Unity package layout](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0jo9any312y6po4id748.png)

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](https://docs.unity3d.com/Manual/cus-samples.html). 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.