edit usage doc

README.md

@@ -64,7 +64,7 @@ Try Truss for yourself on Echo Service to see the service that is generated:
 truss example/echo.proto
 ```
 
-See [USAGE.md](./USAGE.md) for more details.
+See [USAGE.md](./USAGE.md) and [TUTORIAL.md](./TUTORIAL.md) for more details.
 
 ## Developing
 

USAGE.md

@@ -2,19 +2,29 @@
 
 ## File structure
 
-You start with your definition file, named `svc.proto`, in the current
+Start with your service definition file, let's name it `svc.proto`. 
-directory. The current directory should look like this:
+For a more detailed example of a simple service definition see `go-truss/example/echo.proto`,
+but for now we only care about the following structure:
+```
+// The package name determines the name of the directories that truss creates
+package NAME;
+
+// RPC interface definitions
+...
+```
+
+The current directory should look like this:
 
 ```
 .
 └── svc.proto
 ```
 
-Then, you'd run truss on your service definition file, like this: `truss
+Run truss on your service definition file: `$ truss svc.proto`.  
-svc.proto`.  After running truss on your service, `NAME-service` should be
+Upon success, `NAME-service` folder will be created in your current directory. 
-created in your current directory. `NAME-service`, where NAME is the name of
+(`NAME-service`, where NAME is the name of the package defined in your definition file.)
-the package defined in your definition file. Here's what that structure would
+
-look like:
+Your directory structure will look like this:
 
 ```
 .
@@ -40,12 +50,15 @@ Now that you've generated your service, you can install the generated binaries
 with `go install ./...` which will install `NAME-cli-client` and `NAME-server`,
 where NAME is the name of the package defined in your definition file.
 
-To add business logic from this point, you'd edit the `server_handler.go` file
+To add business logic, edit the `server_handler.go` file in `./NAME-service/handlers/server/`.
-in `./NAME-service/handlers/server/`, where NAME is the name of the package
-defined in your definition file.
 
-## *Our Contact*
+## Our Contract
 
-1. Only the files in `handlers/` are user modifiable. The only functions allowed in the handler files are exported functions with the same names as those defined as rpc's in the definition service; all other exported functions will be removed. User logic can be imported and executed within the functions in the handlers.
+1. Modify ONLY the files in `handlers/`.
-2. Do not create files or directories in `NAME-service/`
+
-3. All user logic should exist outside of `NAME-service/`, leaving organization of that logic up to the user.
+ User logic can be imported and executed within the functions in the handlers. It can also be added as _unexported_ helper functions. 
+
+ Truss will enforce that exported functions in `server_handler.go` conform to the rpc interface defined in the service *.proto files. All other exported functions will be removed upon next rerun of truss. 
+
+2. DO NOT create files or directories in `NAME-service/`
+ All user logic must exist outside of `NAME-service/`, leaving organization of that logic up to the user.