From c21d51cc638ebb3d55fcf0eb8292a952c5e7fa1e Mon Sep 17 00:00:00 2001
From: tuneliza <liza@tune.com>
Date: Mon, 5 Dec 2016 16:50:26 -0800
Subject: [PATCH] partial fill-in of tutorial

---
 TUTORIAL.md | 34 ++++++++++++++++++++++++++++++----
 USAGE.md    | 10 ++++++----
 2 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/TUTORIAL.md b/TUTORIAL.md
index 22cff68..d469bc6 100644
--- a/TUTORIAL.md
+++ b/TUTORIAL.md
@@ -1,18 +1,44 @@
-# Tutorial: echo-service example
+# Tutorial
+We will build a simple service based on [echo.proto](./example/echo.proto)
 
-# Installation caveats
+# Installation tips
+1. Follow instructions in the [README](./README.md)
+  - Can use `brew install` to get protobuf, golang, but not other packages
+2. Go to truss installation folder and run `make test`
+  If everything passes you’re good to go.
+  If you see any complaints about packages not installed, `go get` those packages
+  If you encounter any other issues - ask the developers
+3. To update to newer version of truss, do `git pull`, or `go get -u github.com/TuneLab/go-truss/...` truss again.
 
 # Writing your first service
+Define the communication interface for your service in the *.proto file(s). 
+Start with [echo.proto](./example/echo.proto) and read the helpful comments.
+
+## What is in the *.proto file definitions? 
 
-## What is in the *.proto file definitions?
 
 ## Understanding generated structures
 
-## Building the client and server executables
+## Implement business logic
+
+## Build/Run the client and server executables
+
 
 # Additional features
 
 ## File placement
+You can control the location of the output folders for your service by specifying the following flags when running truss
+```
+  -svcout {go-style-package-path to where you want the {Name}-service folder to be}
+  -pbout {go-style-package-path to where you want the *.pb.go interface definitions to be}
+```
+
+Note: “go-style-package-path” means exactly the style you use in your golang import statements, relative to your $GOPATH. This is not your system file path, nor it is relative to location of the *.proto file; the start of the path must be accessible from your $GOPATH. Also no “/” at the end. 
+For example:
+```
+truss -pbout truss-demo/interface-defs -svcout truss-demo/service echo.proto
+```
+Executing this command will place the *.pb.go files into `$GOPATH/truss-demo/interface-defs/`, and the entire echo-service directory (excepting the *.pb.go files) to `$GOPATH/truss-demo/service/`.
 
 ## Middlewares
  TODO
\ No newline at end of file
diff --git a/USAGE.md b/USAGE.md
index 336961d..d9d2922 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -20,7 +20,7 @@ The current directory should look like this:
 └── svc.proto
 ```
 
-Run truss on your service definition file: `$ truss svc.proto`.  
+Run truss on your service definition file: `truss svc.proto`.  
 Upon success, `NAME-service` folder will be created in your current directory. 
 (`NAME-service`, where NAME is the name of the package defined in your definition file.)
 
@@ -52,13 +52,15 @@ where NAME is the name of the package defined in your definition file.
 
 To add business logic, edit the `server_handler.go` file in `./NAME-service/handlers/server/`.
 
+To add middlewares, edit ... (TODO)
+
 ## Our Contract
 
-1. Modify ONLY the files in `handlers/`.
+1. Modify ONLY the files in `handlers/` and `middlewares/`.
 
- User logic can be imported and executed within the functions in the handlers. It can also be added as _unexported_ helper functions. 
+ User logic can be imported and executed within the functions in the handlers. It can also be added as _unexported_ helper functions in the handler file. 
 
- 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. 
+ 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 re-run 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.