Table Documentation Standards

• Overview
• Description Guidelines
• Example Query Guidelines

Overview

Creating table documentation is an important part of developing tables, as each document provides basic table information and example queries that appear on the Steampipe Hub. These example queries are especially important, as they are often the first thing a user will run to explore and understand a new table.

Every table should have a Markdown document with a filename derived from the table name, e.g., docs/tables/aws_acm_certificate.md for table_aws_acm_certificate.go.

Each document should include:

• A header with the table name, e.g., # Table: aws_s3_bucket
• A basic description
• An ## Examples section with multiple example queries

For example, here's a table document for the aws_s3_bucket table:

# Table: aws_s3_bucket

An Amazon S3 bucket is a public cloud storage resource available in Amazon Web
Services' (AWS) Simple Storage Service (S3), an object storage offering.

## Examples

### Basic info

```sql
select
  name,
  region,
  account_id,
  bucket_policy_is_public
from
  aws_s3_bucket;
```

### List buckets with versioning disabled

```sql
select
  name,
  region,
  account_id,
  versioning_enabled
from
  aws_s3_bucket
where
  not versioning_enabled;
```

### List buckets with default encryption disabled

```sql
select
  name,
  server_side_encryption_configuration
from
  aws_s3_bucket
where
  server_side_encryption_configuration is null;
```

When the plugin is packaged and deployed to the Steampipe Registry, this Markdown file will be included in the plugin documentation on the Steampipe Hub.

Description Guidelines

Style Conventions

• Descriptions should be short (1-3 sentences) and provide basic information on the table and its resource type
• All sentences in the description should have the first word capitalized and end with a period
  • Good
    • An AWS IAM user is an entity that you create in AWS to represent the person or application that uses it to interact with.
  • Bad: The first letter should be capitalized and the sentence should end with a period
    • an AWS IAM user is an entity that you create in AWS to represent the person or application that uses it to interact with
• References to resource names should follow the provider's documentation on capitalization
  • Good
    • An AWS S3 bucket is a public cloud storage resource in AWS.
  • Bad: "Bucket" should not be capitalized
    • An AWS S3 Bucket is a public cloud storage resource in AWS.

Example Query Guidelines

Basic Info Example

The first example in each document should be a basic info query. This example query should select commonly used columns from the table and should only contain the select and from keywords.

Example:

### Basic info

```sql
select
  instance_id,
  instance_type,
  region
from
  aws_ec2_instance;
```

Additional Examples

After the basic info query, there should be a few (but at least one) additional example queries that provide an interesting view of the table data. For more information on creating additional example queries, please see Writing Example Queries.

Style Conventions

• Use H3 (###) for example query descriptions, e.g., ### List my resources
• Use SQL Formatter to format all SQL queries
  • Indentation level should be set to 2 spaces per indent level
  • SQL keywords and identifiers should be set to Modify to lower case
  • Please test your queries after formatting them in case unexpected changes are made
• Example descriptions should be in the imperative mood, e.g., List buckets that are..., Count the number of instances...
  • Good
    • ### List unencrypted databases
    • ### List users named foo
  • Bad: Should use "List" instead of "Listing"
    • ### Listing unencrypted databases
  • Bad: Should not include "of"
    • ### List of users named foo
• Example descriptions should use the plural form of the resource name if the query can return more than 1 row
  • Good
    • ### List unencrypted instances
    • ### Get the instance with a specific resource ID
  • Bad: "instance" should be the plural form "instances"
    • ### List unencrypted instance
  • Bad: "instances" should be singular since only one row can be returned
    • ### Get the instances with a specific resource ID
• Example descriptions should follow the provider's documentation on capitalization for resource and property names
  • Good
    • ### List instances with termination protection disabled
  • Bad: "Instances" should not be capitalized
    • ### List Instances with termination protection disabled
• Do not include the service name in descriptions unless its required to differentiate similarly named tables
  • Good
    • ### List buckets in us-east-1
  • Bad: Should not include "S3"
    • ### List S3 buckets in us-east-1