Merge pull request #1169 from google/abel-doc-updates

Update readmes

tools/README.md

@@ -109,3 +109,5 @@ For example:
 **NOTE:** The new building configuration format switches entities being keyed by codes
 to being keyed by guids, and Ids are removed. To convert from old format to the
 new format, run your building configuration file(.yaml) through the [guid generator](https://github.com/google/digitalbuildings/tree/master/tools/guid_generator).
+
+Any questions or concerns can be emailed to **[email protected]**

tools/abel/README.md

@@ -91,7 +91,7 @@ ABEL has a few pieces of core functionality, they are:
   * [Split Workflow](#split-functionality)
 
 ### Command-line arguments for ABEL:
-`-c` or `--credential` absolute or relative path to a gcp OAuth client
+`-c` or `--credential` **required** absolute or relative path to a gcp OAuth client
 credential file. An OAuth client credential is required for authentication
 against Google Sheets service.
 
@@ -118,30 +118,27 @@ against the modified ontology.
 
 ### The ABEL Spreadsheet
 The ABEL spreadsheet serves as a user-friendly interface for ABEL and is what
-allows a user to make changes to machine readable documents like [Building
+allows a user to make changes to machine-readable documents like [Building
 Config](../../ontology/docs/building_config.md).
 
 Please see the [ABEL spreadsheet docs](../../tools/abel/validators/README.md) for detailed instructions on how to create your own spreadsheet.
 
 ### Update Workflow
 
 If you would like to create a building config to update an already onboarded building, then there are two options:
-1. Update an exported building config.
 
-  The process for using a building config to generate an ABEL spreadsheet is as
-  follows:
+Generate an ABEL spreadsheet from an exported building config.
 
   1. In `digitalbuildings/tools/abel` run ABEL with the command:
-  ```
-  python3 abel.py -c /path/to/credential.json -b absolute/path/to/building/config
-  ```
-
-2. Generate a building config from an already updated spreadsheet.
+      ```
+      python3 abel.py -c /path/to/credential.json -b absolute/path/to/building/config
+      ```
+To generate a building config from an already updated spreadsheet.
 
   1. In `digitalbuildings/tools/abel` run ABEL with the command:
-  ```
-  python3 abel.py -s <input_spreadsheet_id> -c <path/to/client_credential.json> -d <path/to/output/directory>
-  ```
+      ```
+      python3 abel.py -s <input_spreadsheet_id> -c <path/to/client_credential.json> -d <path/to/output/directory>
+      ```
   2. If your spreadsheet does not pass the validation criteria found in the
     [spreadsheet docs](../../tools/abel/validators/README.md) then ABEL will fast
     fail and a validation
@@ -158,18 +155,19 @@ If you would like create a building configuration file under the initialization
 The process for using an ABEL spreadsheet to generate a new Building Config is as
 follows:
 
-1. Create a spreadsheet for ABEL from [ABEL Spreadsheet template](https://docs.google.com/spreadsheets/d/1tcLjFnHiXUT-xh5C1hRKiUVaUH_CzgSI8zFQ_B8q7vs/copy#gid=980240783)
-2. Populate your spreadsheet. A well defined guide on how to populate your
+1. Create a spreadsheet for ABEL from [ABEL Spreadsheet template](https://docs.google.com/spreadsheets/d/1nlFVwVvmumBSIAAAv7xq1-xuqGy0k1ONyrG2rMqrgdE/copy#gid=980240783)
+2. Populate your spreadsheet. A well-defined guide on how to populate your
    spreadsheet can be found in the [spreadsheet docs](../../tools/abel/validators/README.md)
 3. In `digitalbuildings/tools/abel` run ABEL with the command:
-```
-python3 abel.py -s <input_spreadsheet_id> -c <path/to/client_credential.json> -d <path/to/output/directory>
-```
-4. If your spreadsheet does not pass the validation criteria found in the
+    ```
+    python3 abel.py -s <input_spreadsheet_id> -c <path/to/client_credential.json> -d <path/to/output/directory>
+    ```
+4. Choose option 2: Create a spreadsheet for a new building
+5. If your spreadsheet does not pass the validation criteria found in the
    [spreadsheet docs](../../tools/abel/validators/README.md) then ABEL will fast
    fail and a validation report will be created in the directory specified with the `-d` arguments with the name,
    `spreadsheet_validation_<todays_date_and_time>.log`
-5. The resulting Building Config and instance validation report will be written
+6. The resulting Building Config and instance validation report will be written
    to the same directory with names:
    * `bc_export_<today_date_and_time>.yaml`
    * `instance_validation_<today_date_and_time>.log`

tools/abel/validators/README.md

@@ -58,6 +58,10 @@ A [human-readable code](../../../ontology/docs/building_config.md#identifiers) f
 [UUID4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) [identifier](../../../ontology/docs/building_config.md#identifiers) for a building.
 Unless you are onboarding a Google building, this value is generated by ABEL and does not need to be provided for initial onboarding.
 
+`Etag` *string*
+
+Version control tag for entities in an entity type database. Used only when updating an existing building config.
+
 ***Note:*** A Site should not be considered an entity and should not be listed in
 the `Entities` tab.
 
@@ -108,6 +112,8 @@ An [update operation](../../../ontology/docs/building_config.md#update) for an e
 * `DELETE` - Must be indicated by a user that an entity is being removed from a building.
 * `EXPORT` - Will be generated automatically and indicates that an entity exists in a building.
 
+Operation specifies if and how an entity is being updated from an existing configuration. 
+
 ### Entity Fields
 
 The `Entity Fields` tab defines fields translated by [reporting entities](../../../ontology/docs/building_config.md#reporting-physical-devices) and linked to [virtual entities](../../../onotology/docs/building_config.md#virtual-devices) defined in the `Entities` tab.