Documentation and Packaging Standard¶
Every shipped product needs included instructions¶
Every product distributed to a customer must include usage instructions accessible within the product itself — typically the Start Here / Instructions tab described in workbook-architecture-standard.md — so a customer never has to leave the file to understand how to use it. A separate standalone instructions document may supplement, but not replace, in-product instructions.
Every shipped product needs a changelog¶
Every product must maintain a changelog recording what changed between versions,
starting from its first release. The changelog should be understandable to a customer
(what changed and why it matters to them), not just an internal commit log. It lives
within the product's directory under products/<slug>/releases/.
Clear versioning¶
Products must use a consistent, documented versioning scheme (semantic versioning — major.minor.patch — is the default expectation unless a product's specification states otherwise) so customers and support staff can unambiguously identify which version a customer has and what's changed since.
Consistent packaging for distribution¶
When a product is packaged for distribution (e.g., as a downloadable .zip):
- The archive should have a consistent, predictable structure across products in this venture (e.g., the workbook file itself, a readme, any supplementary files, kept at a shallow and clearly labeled directory depth).
- File names should be consistent and descriptive — including the product name and
version — rather than generic (avoid names like
Book1.xlsxorfinal_v2.xlsx). - Any supplementary files (quick-start PDF, license/usage terms) should be named and organized consistently across products, so a customer who's purchased more than one Digital Products tool has a familiar experience unpacking each one.
Relationship to marketplace listings¶
Documentation and packaging quality directly supports the honesty requirements in marketplace-listing-standard.md — a well-documented product is easier to represent accurately in a listing, and reduces support burden and refund risk from confused customers.