Doc Upgrade - TS v7.0 Admin: "How to Use tabcmd"

Available online here, the original doc is very confusing; its problems are discussed here.
The improved doc is here.

The original doc

---

How to Use tabcmd

tabcmd takes a command, an argument, and options as shown in the format below:

tabcmd command command-argument [options option-arguments]

Using that format and the commands in this document you can run the tool. For example, you could use the following command to create a session on a server called sales-server logged in as Administrator and delete a workbook on the Sales site called Sales_Analysis:

tabcmd delete "Sales_Analysis" -s sales-server -t Sales -u administrator -p p@ssw0rd!

Here’s the same command for a workbook on the Default site, or for a server that is not running multiple sites:

tabcmd delete "Sales_Analysis" -s sales-server -u administrator -p p@ssw0rd!

When the command is successful, tabcmd will return a status code of zero. A full error message for non-zero status codes is printed to stderr. In addition, informative or progress messages may be printed to stdout. A full log named tabcmd.log that includes debugging, progress, and error messages is written to:

• Windows 7, Windows Vista, and Windows Server 2008 R2: C:\Users\\AppData\Roaming\Tableau
• Windows Server 2003: C:\Documents and Settings\\Application Data\Tableau

---

...

Improved doc

---

How to Use tabcmd

Sessions

tabcmd runs inside an authorized environment called a session.

Sessions are used to identify the Tableau Server the tabcmd will run on. They also need to be run on behalf of an authorized User. because of these, the server name, user name and password need to be provided. See the online doc for further information.

tabcmd details

tabcmd has this format:

tabcmd command command-argument [options option-arguments]

The commands are listed online here with their arguments and options.

Using this format and the commands in this document you can run the tool.

For example, you could use the following command to delete the "Sales_Analysis" workbook* or data source* from the 'Sales' site on the 'sales-server' Tableau Server, where the command is executed as the 'administrator' user:

tabcmd delete "Sales_Analysis" -t Sales -s sales-server -u administrator -p p@ssw0rd!

Here’s the same command for a workbook on the Default site, or for a single-site server (note the missing "-t Sales" option):

tabcmd delete "Sales_Analysis"          -s sales-server -u administrator -p p@ssw0rd!

Notes:

* The delete command's argument is by default the name of a workbook or data source.
See tabcmd Commands – delete workbook-name or datasource-name for more information

When the command is successful, tabcmd will return a status code of zero. A full error message for non-zero status codes is printed to stderr. In addition, informative or progress messages may be printed to stdout. A full log named tabcmd.log that includes debugging, progress, and error messages is written to:

• Windows 7, Windows Vista, and Windows Server 2008 R2: C:\Users\\AppData\Roaming\Tableau
• Windows Server 2003: C:\Documents and Settings\\Application Data\Tableau

---

...

The original doc's problems

---

The explanation is mangled, hard to follow, and actually impedes comprehension.

All by itself the explanation is unclear.
"For example, you could use the following command to create a session on a server called sales-server logged in as Administrator and delete a workbook on the Sales site called Sales_Analysis:"

Worse, when one is reading the actual command, relating it back to the explanation is very difficult: the command being read doesn't map back well to the explanation just read.

Problems include:

• The lead is buried

  The most important thing to know about this command is that something is getting deleted.

  But the communication that something will be deleted doesn't occur until the 14th word following "For example, you could use the following command to", which makes it buried as the 23rd word in the sentence.

• What's a session?

  "session" is the first noun in the explanation, implying that it's a significant thing, so the reader is primed to anchor it in whatever follows. But it's never seen again, and since the User is expecting it—it is important, after all—the further on the reader goes, the greater the confusion becomes trying to resolve the dangling reference.

  Sessions don't matter

  in this context, so there's no reason to mention them, much less promote them to the first position, which needs to be where the most important thing needs to be.

• The order of explanation elements is different from the order of command elements, i.e.:

  The explanation's elements, in order:	The command's elements, in order:
  "session", never seen again "server" server name: sales-server login ID: Administrator n.b. case doesn't match command function: "delete" function object: type Tableau Server object: type/name, i.e. site/Sales function object: "Sales_Analysis" n.b. needs to back-reference 3 steps	function: "delete" function object name: "Sales_Analysis" option - identify server: "-s sales-server" option - identify site on server: "-t Sales" option - identify User by name: "-u administrator" option - identify User's password: "-p p@ssw0rd!"

  Try to relate these two lists of elements. Even when laid out clearly it's difficult to make sense of their relationships.

• Inconsistent naming structure

  Compare these two clauses:
  • create a session on a server called sales-server
  • delete a workbook on the Sales site called Sales_Analysis

  In the first clause, the final label—"sales-server"—applies to the second noun—"server".
  In the second clause, the final label—"Sales_Analysis"—applies to the first noun—"workbook".

  It's extremely difficult to parse these two clauses to arrive at an internally consistent meaning that corresponds to the actual tabcmd command.

  In order to understand the explanation the reader must realize that it's inconsistent internally and with the actual command, and then puzzle out the truth for him- or herself.

  This is bad.

• Other internal explanation inconsistencies:

  create a session on a server called sales-server	Is "sales-server" the name of the session or server? Maybe both?
  logged in as Administrator	nothing wrong here
  delete a workbook on the Sales site called Sales_Analysis	Why is a workbook deleted, not something else? Even after looking at the command doc it's not clear, but that's another friction point. Is "Sales_Analysis" the workbook name, or the name of a site on something named "Sales"? In reality, "Sales_Analysis" is the workbook name, but it takes a two-step back-reference, and recognizing the fact from the confusing and unreliable explanation for this to be clear. Or it takes understanding the tabcmd command structure to know this, highlighting the danger of documentation being written by someone who knows the material but not how to think like someone who doesn't.

• I could go on, but the horse is well beaten.