Best Practices for Grid Feature Documentation

A new Grid feature (such as Product, Location, or Identity) should have the following documentation before the feature is considered complete.

▢   Feature overview
▢   How-to procedure
▢   Smart contract specification
▢   Database tables reference
▢   GS1 schema reference
▢   REST API Reference
▢   Rust SDK documentation
▢   CLI Command Reference
▢   Man pages for grid subcommands

Grid documentation is written in GitHub Flavored Markdown.

Read on to learn what’s needed for each item.

Feature Overview

Provide a high-level description that is focused on business-level concepts and benefits. Some technical information is appropriate, but details belong in the procedure and reference material. Include links to the detailed information as appropriate.

Example: Splinter: Canopy Application Framework

How-to Procedure

Write a procedure for each task associated with the feature, such as creating a new product or setting up Pike organizations, agents, and permissions.

  • Start with a introduction that explains the end goal for the procedure, where it fits in the Grid ecosystem, and the intended audience for the procedure (who usually does this task).

  • Include any assumptions (like requiring an existing circuit) and prerequisites such as user keys, service IDs, or example YAML files that will be used in the procedure.

  • Then list the steps for the task (such as creating and managing products with command-line options and YAML schema files). Include example commands and output for each step. For extra credit, add troubleshooting tips for common problems.

Example: Creating Splinter Circuits

Smart Contract Specification

Provide a topic that describes the smart contract’s objects, namespace, address format, and transaction types.

Examples: Grid Product Smart Contract Specification, Sawtooth Transaction Family Specifications

Database Tables Reference

Provide a reference topic that describes the Grid daemon’s database schema, as defined in grid/daemon/src/database/

Examples: Splinter: Biome Database Tables, Splinter: Gameroom Walkthrough (see Section I-2.8, “Gameroom daemons write notification to Gameroom database”)

GS1 Schema Reference

Provide a reference topic that describes the Grid GS1 schema. This topic should list the supported GS1 fields and associated GS1 attributes.

REST API Reference

Update the Grid Daemon’s openapi.yaml file to describe the feature’s REST API endpoints. The Grid REST API Reference is automatically generated from the contents of this file.

Example: splinterd REST API Reference: Splinter Registry

Rust SDK documentation

Include rustdoc comments for any SDK items associated with the feature. The Grid Rust SDK Reference is automatically generated from these comments.

Provide a description and overview for each new module, plus a description for each struct, function, feature-specific enum, and so on.

Example: track_and_trace protocol module in the grid_sdk crate documentation

CLI Usage Statements

Each grid subcommand should have clear, helpful usage information for the output of grid {SUBCOMMAND} --help.

Man Pages

Write a man page for each grid subcommand associated with this feature. The man page should expand on the CLI usage (which is minimal by design).

  • DESCRIPTION section: Summarize what the command does, explain why someone would use it and where it fits in the Grid ecosystem (such as in multi-step task), and provide general guidance and prerequisites.

  • OPTIONS section: Include details about the syntax, default values and any related environment variables, usage tips, and other helpful information.

  • EXAMPLES section: Unless the command syntax is extremely basic, provide at least one example of a common use with default values. If appropriate, also provide more complex examples, such as using inter-related options, specifying a non-default file path, or overriding settings in a YAML file.

If this feature adds a top-level subcommand (such as grid product or grid location), update the man page to include the new subcommand in the “SUBCOMMANDS” section.

Examples: Splinter man page template, splinter(1), splinter-circuit(1), splinter-circuit-propose(1)

CLI Command Reference

The grid man pages are automatically included in the Grid CLI Command Reference.

When adding a new Grid command or subcommand, update the Grid CLI Command Reference with a link to the new man page.