Notes on new user documentation

[arvados.git] / doc / user / sdk-cli.textile

diff --git a/doc/user/sdk-cli.textile b/doc/user/sdk-cli.textile
index 99bd30386d25fe315dccd5d68edef4b93c29a22c..55e477db576a77bd39de05c2738be08a3f0ee267 100644 (file)
--- a/doc/user/sdk-cli.textile
+++ b/doc/user/sdk-cli.textile
@@ -1,7 +1,7 @@
 ---
 layout: default
 navsection: userguide
-title: Command line SDK
+title: "Intro: Command line SDK"
 navorder: 10
 ---
 
@@ -9,11 +9,12 @@ navorder: 10
 
 h1. Command line SDK
 
-If you are logged in to an Arvados VM, the command line SDK should be
-installed. Try:
+If you are logged in to an Arvados VM, the command line SDK should be installed. Try:
 
 @arv --help@
 
+_Help is not helpful.  See bug #1667_
+
 h3. First...
 
 Set the ARVADOS_API_HOST environment variable.
@@ -22,16 +23,22 @@ Set the ARVADOS_API_HOST environment variable.
 
 Log in to Workbench and get an API token for your account. Set the ARVADOS_API_TOKEN environment variable.
 
-@export ARVADOS_API_TOKEN=c0vdbi8wp7f703lbthyadlvmaivgldxssy3l32isslmax93k9@
+@export
+ARVADOS_API_TOKEN=c0vdbi8wp7f703lbthyadlvmaivgldxssy3l32isslmax93k9@
 
 If you are using a development instance with an unverifiable SSL certificate, set the ARVADOS_API_HOST_INSECURE environment variable.
 
 @export ARVADOS_API_HOST_INSECURE=1@
 
+_This should link back to "api-tokens":api-tokens.html instead of
+re-explaining it__
+
 h3. Usage
 
 @arv [global_options] resource_type resource_method [method_parameters]@
 
+_This is what arv --help really ought to print out_
+
 h3. Basic examples
 
 Get UUID of the current user
@@ -44,7 +51,7 @@ Get entire record for identified user
 @arv -h user get --uuid 6dnxa-tpzed-iimd25zhzh84gbk@
 
 Update user record
-@arv user update --uuid 6dnxa-tpzed-iimd25zhzh84gbk --first_name "Bob"@
+@arv user update --uuid 6dnxa-tpzed-iimd25zhzh84gbk --first-name "Bob"@
 
 Get list of groups (showing just UUIDs)
 @arv group list@
@@ -54,6 +61,9 @@ Get list of groups (showing entire records)
 
 h3. Global options
 
+_Move these up to before "basic examples", and give examples of what
+these options do and how they might be useful._
+
 - @--json@, @-j@ := Output entire response as compact JSON.
 
 - @--pretty@, @--human@, @-h@ := Output entire response as JSON with whitespace for better human-readability.