Vrtk: Provide better documentation.

[thestonefox]

At the moment the only documentation is a basic Getting Started guide GETTING_STARTED.md and API documentation DOCUMENTATION.md which is one file that contains all the API docs for each class and prefab.

Proposal:

The documentation should be split up into separate files and go into a Documentation folder structure like:

---

• Documentation/
  
  
  
  • Getting Started/
    
    
    
    
    
    • SDK Setup
      
      
      
      
      
      
      
      • _SteamVR.md_
      
      
      
      
      • _OculusUtilities.md_
      
      
      
      
      • _OculusAvatar.md_
      
      
      
      
      • _....etc_
      
      
      
      
    
    
    
    • Learning the Basics/
      
      
      
      
      
      
      
      • _Setting up a pointer.md_
      
      
      
      
      • _Setting up grabbable objects.md_
      
      
      
      
      • _Setting up usable objects.md_
      
      
      
      
      • _Interacting with pointer.md_
      
      
      
      
      • _Locomotion with teleporting.md_ (covers basic/height adjust/dash)
      
      
      
      
      • _....etc_
      
      
      
      
    
    
    
  
  
  • Tutorials/
    
    
    
    
    
    • _How to do something that I can't think of an example for right now.md_
    
    
    
    • _....etc_
    
    
    
  
  
  • API/
    
    
    
    
    
    • Interactions/
      
      
      
      
      
      
      
      • _VRTK_InteractGrab.md_
      
      
      
      
      • _....etc_
      
      
      
      
    
    
    
    • Locomotion/
      
      
      
      
      
      
      
      • _....etc_
      
      
      
      
    
    
    
    • Presence/
      
      
      
      
      
      
      
      • _....etc_
      
      
      
      
    
    
    
  
  

---

This document structure would also be mirrored on the readme.io site.

All documents would also follow common docs guidelines, these guidelines could be stored in the documentation direction called GUIDELINES.md

All API docs (scripts and prefabs) would have specific guidelines of how the docs would be written. All Getting started and tutorials would also include guidelines.

Any images required in documentation would need to be stored on github as github image links.

[thestonefox]

I think the example scenes should be self documented within the example scene by using in game text on tooltips and other things maybe.

We could also have another directory called Examples and each example scene has a write up of how things are set up maybe?

[andybak]

I've started a Google Doc to keep track of what seems to be the minimal steps for basic functionality: https://docs.google.com/document/d/1024kS1ZEOD21-UCcYNy2Ibsj6MRHBm3c241O-CIHrvk/edit?usp=sharing

There's a few places where I wonder if VRTK should not be configuring itself automatically. For example step 4 of "Basic pointer" confused me for a bit and I had to go and look at the example scene to work out the step I'd missed. Could this not default to the first pointer renderer subclass on the current object?

[thestonefox]

I'm torn on the magic behaviour of auto populating things. Like some scripts do this already whereas others don't.

I'm not sure if it's good to magically hook things up if they can be hooked up (e.g. if the scripts are on the same GameObject then just link them). I think the reason it doesn't do it for the pointer is what if you have two renderers on the same GameObject (one is a straight and the other a bezier) which one should link? I could be overthinking that though.

It something we should probably make a rule for though that scripts either all at least attempt to look up, or none do and you have to explicitly link them.

[andybak]

"make the easy things easy and the hard things possible"

Not sure if that applies 100% in this context but I've always felt a framework should support the common cases with as little configuration as possible - as long as it doesn't get in the way when you need to do something different.

So in this case - if you do have two renderers then the what's going to go wrong?

1. You add VRTK_Pointer
2. You add VRTK_StraightPointerRenderer
3. VRTK automatically wires it up
4. You add VRTK_BezierPointerRenderer
5. You change the setting so that it points at VRTK_BezierPointerRenderer

There's no extra step and it's unlikely you're going to forget or not figure out what to do - anyone adding two renderers isn't a complete noob.

But the danger in not doing it automatically is that the common case requires more work - and more importantly - it's another place where a beginner could get completely stuck.

So I'd argue for always doing the obvious thing automatically but making it easy to spot and simple to override.

[thestonefox]

There's nothing to say which pointer renderer Unity will auto wire up.

Problem with magic in scripts is it causes more confusion in the end because people are not aware of what's going on.

[andybak]

"If PointerRenderer is none and the user has just added a renderer to this gameobject then they probably want to use it"

people are not aware of what's going on.

It's about aiming to be beginner friendly and expert friendly. You can have you cake and eat it as long as the "magic" is simple, predictable and explicit. Frameworks and APIs have UX and it's good UX to reduce boilerplate and reduce the need for repetitive actions.

They key thing is that PointerRenderer is visible and explicit. If it was hidden away then I'd agree with you but it's right there in the inspector. Unless there's a common case where the user would want it to be None then I don't see how setting a sensible default ("Hey! let's connect to the renderer that's been added to this gameobject") would cause that much confusion - at least compared to the benefit of having common behaviours become ridiculously easy to set up.

[thestonefox]

There may well be a reason someone wants it blank (perhaps they want to set it up themselves later).

This is the issue with magic code. You can't figure out why it's doing what it's doing without looking at the code.

[andybak]

I think you still misunderstand me but this isn't the right place to continue this discussion. (One day, over a beer maybe...)

Back to the original point - is the stuff in the Google Doc useful? It's useful for me so I'll probably continue to some extent but if it's useful for your work on the docs that's added incentive.

[thestonefox]

@andybak I think we should continue the discussion. I've asked for more people to throw in their opinion. I'm not against the auto hooking up (as i say things already do this). But I think we need to have it consistent approach. So if auto hooking is deemed ok by people then we should do it everywhere, but if it's deemed magic, then we should do it nowhere. At the moment it's confusing that some things do it and some don't.

[thestonefox]

Also, the google docs stuff is good. It's always good to note this stuff down to help improve the documentation.

[andybak]

I think we should continue the discussion.

How about a new ticket? It's not really related to the docs per se.

[thestonefox]

Yeah new ticket sounds good

[thestonefox]

Also include links in the scripts to the docs

https://docs.unity3d.com/ScriptReference/HelpURLAttribute.html

[jameskane05]

Hey, @thestonefox, I'm James, a developer and writer-editor from St. Louis. I think I could help w/ this! I'm really impressed with VRTK (have been playing around with it for about a week) and would be happy to help make it more accessible via better docs. I'm interested in diving more deeply into some of the code myself and I think I'd be well-positioned to delve into both technical detail and more beginner-friendly tutorials.

What's your take on scope for these docs? I've noticed you don't currently explain any of the components/scripts w/ code examples. Is the idea that you shouldn't have to, or is this something you're interested in adding? For me, an interesting benefit of VRTK is being able to pull up the script for your implementation of "bezier pointer" for instance, and see it how's done. But maybe you're thinking more like, "Add this script to your GameObject, then drag-and-drop this and voila!" and prioritizing that as opposed to explanation of the underlying code.

Here's some VR-related writing I've done recently. It's more editorial in style, but should demonstrate some familiarity with the subject matter:

https://medium.com/@jameskanestl/the-coming-wave-of-vr-creation-tools-9080d4206111

Let me know what you think, thanks!

[thestonefox]

Hey @jameskane05 I think we're on the same page when it comes to written docs.

I like the idea of written tutorials showing how to set up the basic scripts with simple examples, kinda like written versions of the videos on videos.vrtk.io

We have structured the repo to allow for this as well.

[andybak]

Just a reminder that I'm still (slowly) working on my "cookbook" approach to the docs. I'm finding it useful myself and I've validated they work so far with a someone else who was learning VRTK. Happy if anyone wants to contribute/criticise/steal/borrow

https://docs.google.com/document/d/1024kS1ZEOD21-UCcYNy2Ibsj6MRHBm3c241O-CIHrvk/edit?usp=sharing

[thestonefox]

Closing this as it's related to an older version of VRTK (v3.3) the master branch is now on VRTK v4. Feel free to request to reopen if the issue is still present.