Good Examples of Asset Documentation

[Kellyrayj]

Hi friends,

I’m quietly working on a little package that I’d like to put on the asset store and I’m searching for some solid examples of how to do the documentation.

I am thinking about things like, how do you strike a balance between cohesive instruction vs too much information?

How safe is it to assume the buyer can figure out the basics of Unity? For instance, I could write “Add the whatever component to the game object.” Or I could write more descriptively, “With the game object selected, click the ‘add component’ button under the inspector panel and add the whatever component to the game object.”

Should the documentation serve to give an overview of the product? Or should you do that with video?

Did you find video instruction to be helpful? Or a waste of time?

Thanks in advance!

[Ony]

@Kellyrayj

“Add the whatever component to the game object.”

That’s what I prefer. I know how to use Unity so I only need to know how your asset fits in. With that said, it totally depends on the asset. If it’s something geared towards newbies then yeah you might have to go into more detail. If it’s something for advanced users then it’s not really necessary.

@Kellyrayj

Should the documentation serve to give an overview of the product? Or should you do that with video? Did you find video instruction to be helpful?

Depends on the asset but as a whole, speaking for myself, I’d rather have good written docs than a video any day. Unless you can make a short, clear, concise, good quality video that gets to the point then I’d recommend staying away from video docs.

There was an asset I was looking at in the store the other day, and they had a video doc on YouTube as the only real info about how to use the product. I went to watch the video and it was horrible. 25 minutes. Bad sound quality, a lot of “uhms, and ers” and it took forever just to get to the point. On top of that, the developer didn’t edit out the “waiting period” where the asset was doing something, so there are long periods of nothing with him saying “it sometimes can take a while”. Really?? Edit it out! Needless to say, I closed the video after five minutes and then skipping around, then I closed the Asset Store page. Their video cost them the sale. If they’d just had a simple document I could look at then they may have got me to buy.

[theANMATOR2b]

I personally prefer written documentation - off line is best so I don’t have to be connected.

Additionally if your asset improves or replaces a workflow in Unity - I think it would be important to point that out and show how this asset with a new workflow is improved over the Unity way. So you may want to add in some detail about the old workflow.
Example description with example asset - this really does not exist yet:
This asset automatically retargets animations onto any rig -including quadrupeds regardless of the bone structure. All you have to do is select the character, and the separate animation at the same time and click the retarget button. This workflow is an improvement over the base retargeting process where you have to match the bone structure and/or bone names of the character and make sure the avatars match.

[JohnnyA]

Although I’m still fleshing out some details (only released a few weeks ago) I think I’ve done a pretty good job with Platformer PRO. In general I use the more terse form, and save the step-by-steps for video tutorials. Although a couple of the documentation pages are particularly aimed at beginners and favour the step-by-step.

Online doco: https://jnamobile.zendesk.com/hc/en-gb
A static version of this is included in the package.

Plus some video tutorials: https://www.youtube.com/playlist?list=PLbnzW2Y4qytLJINKyXDtj2f4MJFsYutNP
(More coming soon)

Link to these in the editor:

(And yes this is a bit of shameless self promotion )

[JohnnyA]

I’ll add that despite this some users still ask questions about stuff in the manual, sometimes because they haven’t looked, and sometimes because its not clear enough.

My next step is adding Help button against every component which links directly to online manual.

[TonyLi]

I’ve found that users are split down the middle between written documentation and video tutorials, so you should do both. Some people won’t consider a product without video tutorials, others without good written documentation. Neither need to be long; they just need to be clear and effective. Contextual help buttons, like @JohnnyA mentioned, are really useful, too.

Video folks look for three things:

• An overview video to help them decide whether the asset fits their needs,
• A quick start video that shows them how to get the basic system working, and
• Lots of short, detailed, step-by-step tutorials for individual steps.

You can also include the overview video on your Asset Store page.

Before recording a video, write a script and record some practice runs. If you don’t have a decent mic (the Blue Yeti is great, btw), don’t record audio. Just overlay text comments in post-production. Once your video is out there, it’s out there forever. I made this mistake on some of the earlier Dialogue System videos.

Written manual folks look for:

• A quick overview of the example scene(s),

• A one-page quick start tutorial,

• A more detailed, step-by-by configuration guide,

• A separate reference section for all the nitty-gritty details (to keep #1 and #2 above short), and

• An API reference if your asset has any code.

Many users head straight to the example scene(s) to see the product in action before reading documentation. If your manual starts with an explanation of the example scene, it gives them a grounding for the rest of the manual.

Love/Hate’s manual (PDF available on this page) has been pretty well received. A lot of people like the Dialogue System’s hyperlinked manual, but like Unity’s own hyperlinked manual it’s difficult for those who want to print out the whole thing for an offline hardcopy.

Also record every customer question in a FAQ document, with an eye to incorporating it into the manual. Otherwise you’ll end up answering the same question a hundred times, which isn’t fun for you, and it’s frustrating for users to have to wait for a response when they could have looked it up in the manual if the info were there.

Take the time to make the manual as polished as you can. Before you publish it, run it by several testers who are new to your product (“kleenex testers”). If they get snagged on any parts of it, that’s where you’ll get frustrated support requests. Time you spend polishing the documentation beforehand will pay off tenfold in reducing support requests, plus you’ll have happier customers.

BTW, personally when I’m using an Asset Store product, I refer to written documentation more than videos. But I’ll watch a video if something’s unclear in the writing.

Best of luck!

[jerotas]

@JohnnyA

My next step is adding Help button against every component which links directly to online manual.

We’re currently doing the same thing with our plugins, reducing the readme doc from 56 pages to about 9 That was just too long for a lot of people to bother searching.

Our Inspectors have lots of collapsible sections so we actually have several help icons on each in some cases pointing to the correct part of the page of online documentation.

Then I was going to include the entire online documentation website as a zip for people who are paranoid the website might disappear one day.

[jerotas]

@TonyLi

Before recording a video, write a script and record some practice runs.

A different method works for me. I do decide what I’m going to show up front, but no “script” prepared (not reading anything). I record the video only (no audio) while talking to make sure the pace is appropriate. If I did unnecessary stuff with the mouse or clicking around then I nuke that take and start again. When finished with video, then I record the audio only while playing back the video. This part takes longer because I make sure there are no ums, ers or unneeded words.

Then I edit them all together. May work better or worse than Tony’s method depending on how well you ad lib

@TonyLi

Once your video is out there, it’s out there forever.

I figured out a way around this problem. You can always make an updated video and nuke the old one. One way to make this work without breaking old links in documents and web pages is to make sure to point to a Youtube Playlist (could be a single video in it) instead of a direct video link. Then just update the Playlist by deleting the old video from it and adding the new one.

[Ony]

@jerotas

A different method works for me. I do decide what I’m going to show up front, but no “script” prepared (not reading anything). I record the video only (no audio) while talking to make sure the pace is appropriate. If I did unnecessary stuff with the mouse or clicking around then I nuke that take and start again. When finished with video, then I record the audio only while playing back the video. This part takes longer because I make sure there are no ums, ers or unneeded words.

I would think that’s the better way. It allows you to concentrate on one thing at a time instead of trying to talk while doing the work.

[TonyLi]

@Ony

I would think that’s the better way. It allows you to concentrate on one thing at a time instead of trying to talk while doing the work.

I agree, too. By “script,” I mostly just mean planning what you want to demonstrate. I’ve seen a lot of videos where the presenter wastes a lot of time fumbling and backtracking because he or she doesn’t have a plan and doesn’t have jerotas’ perfectionism to record more takes.

[jerotas]

@TonyLi

I agree, too. By “script,” I mostly just mean planning what you want to demonstrate. I’ve seen a lot of videos where the presenter wastes a lot of time fumbling and backtracking because he or she doesn’t have a plan and doesn’t have jerotas’ perfectionism to record more takes.

Yeah I saw some of those kinds of videos before making ours, luckily. I found them unprofessional so wanted to avoid that sort of thing.

[JohnnyA]

@TonyLi

I agree, too. By “script,” I mostly just mean planning what you want to demonstrate. I’ve seen a lot of videos where the presenter wastes a lot of time fumbling and backtracking because he or she doesn’t have a plan and doesn’t have jerotas’ perfectionism to record more takes.

The video making is definitely time consuming, particularly when you are recording in a house with two kids under three running around, half my videos a rerecorded in my ‘sound studio’ (i.e. backseat of my car)

[LaneFox]

Personally I made a Getting Started doc to cover all of the major inspectors and stuff but plan on making API docs later. Less is always more. I recommend writing the first few things that come to mind when you’re making docs, getting a rough draft, stepping through it bit by bit and then trying to condense it as much as possible without losing value. Really, it takes a good chunk of time to make proper documentation…

You are sometimes required to have offline docs (like for Template category products) so that may put a dent in plans if you were planning to do nice online html stuff you can maintain separately.

If you’re planning on making API docs you can use stuff like doxygen for free and it will certainly spew out a totally functional HTML document for navigating your source but will require a lot of internal code documentation on stuff to really be useful. ie summaries, descriptions, etc… written inside your source.

[Kiwasi]

@jerotas

A different method works for me. I do decide what I’m going to show up front, but no “script” prepared (not reading anything). I record the video only (no audio) while talking to make sure the pace is appropriate. If I did unnecessary stuff with the mouse or clicking around then I nuke that take and start again. When finished with video, then I record the audio only while playing back the video. This part takes longer because I make sure there are no ums, ers or unneeded words.

This. If you are going to make a video make it a decent one. That means video first, with no audio. Then edit the video for conciseness. Then record audio.

I typically start with about an hour of video for every fifteen minutes that makes the final cut. Recording and editin is time consuming.

You also want good text documents. Videos are great for getting a quick overview if the features, and some how to stuff for the major tasks. But nothing beats a decent text reference for getting down into the details.

[superpig]

BTW, those of you who are adding Help buttons to your components: Are you using HelpUrlAttribute, or rolling your own solutions?

[jerotas]

@superpig

BTW, those of you who are adding Help buttons to your components: Are you using HelpUrlAttribute, or rolling your own solutions?

Didn’t know about that. I’ve never clicked that Help icon in my life lol. No I’m rolling my own. As I said, we need several per Inspector, so mine looks like this (not quite done yet). Each section has a green help icon that does Application.OpenURL