Documentation Plan for Notary v2, ORAS, Ratify

# Documentation Plan for Notary v2, ORAS, Ratify ## Goals 1. To comfirm the documentation structure for Notary v2, ORAS, and Ratify. 2. To develop developer-friendly user manual content. 3. Clarify the project status and content delivery timeline. ## Documentation Structure A high-level overview to the general structure (directory) demonstrates how it’s organized will help readers quickly know where to look for certain things: - **Introduction**: Basic introduction to the project, concepts, user scenarios, user values, quickstart, etc. - **Installation**: How to install the project on different platforms or environments - **Tutorials**: Take you by the hand through a series of steps to create your first demo. Start here if you’re new to the project. - **How-to guides**: Guide you through the step-by-step usage involved in addressing key problems and use-cases with ecosystem tools. They are more advanced than tutorials and assume some knowledge of how the project works. - **Community Guides**: discuss topics centered around developer guide, release process, contributing guide. - **Glossary**: Explain technical terms and concepts - **FAQ and Troubleshooting**: ## Notary v2 - **Project status**: Alpha 4 - **Documentation status**: Almost empty. The project spec is comleted. Only two quickstart guides existed, see below: - [Hello World for Notation: Local signing and verification](https://github.com/notaryproject/notation/blob/main/docs/hello-signing.md) - [Build, sign, and verify container images using Notary and Azure Key Vault](https://docs.microsoft.com/azure/container-registry/container-registry-tutorial-sign-build-push) Documention plan **Initial plan before KubeCon (Oct 24)**: Complete the chapters including introduction, installation, tutorials, glossary. ### New Documentation Directory Category | Documentsn | Status | Need review existing docs? | refreshing -- | -- | -- | -- | -- Quick Start | Quick start | 1/1 | Yes | per new release Installation guides | Installation guide | 1/1 | Yes | per new release Tutorials | * Sign a container image * using a local key for testing purpose * Sign a container image using a key stored in Key vault (Azure Key vault or AWS KMS) * Sign artifacts (e.g SBOM file) stored in a registry * List artifacts and associated signatures stored in a registry * Verify signatures using trust store and trust policy * Build a plugin * Others: like Ratify validation | 0 | | Per new feature How-to guides | * Explain Directory structure after installation of notation CLI * Configure signing keys * Configure a different signature envelope * Configure trust policy * Configure trust store * Install/uninstall plugins | 0 | | Per new feature Concepts | Concept | 1/1 | Yes | per new release Troubleshooting | Troubleshooting guide | 0/1 | | Per new feature Frequently asked questions | FAQ | 1/1 | Yes | per new release specifications | A page to add links to each spec in different repos under notaryproject | 0 | | Per new spec ### Other Work Items on the Website Chapters | Documents | Status | Need to review and update existing docs | Maintenance frequency | -- | -- | -- | -- | -- Landing page | Redesign a new landing page | 0 | | basically unchangedKey feature announcement | 0 | | per new key feature or per new release Blog | * Cloud provider story (e.g. AWS or Azure) * Other types of documents not in Tutorials and how-to categories (e.g. Secure supply chain related） | | | per new release Roadmap | https://github.com/notaryproject/roadmap | | Yes | Per milestone update ## ORAS - **Project status**: Release Candidate - **Documentation status**: Only a few CLI user guides, SDK examples, and basic introduction on the ORAS website. Another [ORAS quickstart guide](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-oras-artifacts) is available on the Azure doc. ### New Documentation Directory Chapters | Documents | Status | Need to review and update existing docs? | Refreshing -- | -- | -- | -- | -- Overview of ORAS | - What is ORAS - Use cases - Demos - Roadmap | 2/4 | Yes | Per new release. Maintained by PM Installation | Install ORAS CLI on multiple platforms | 1/1 | Yes | Per new release Getting Started | ORAS CLI quick start | 0 | | Per new release CLI Guides | - Authentication (login and logout) - Pull and push artifacts - Attach files to artifacts - Copy artifacts across registries - Discover referrers of a manifest - Repository and tag operations - Manifest and blob operations | 3/7 | Yes | Per new release How-to guides | - Using ORAS in Secure Supply Chain - Using ORAS in CI/CD (e.g. GitHub Actions) - Working with OCI Registries - Using ORAS with Kubernetes manifest | 1/4 | Yes | Per new release and E2E scenario Development and contribution | - How to build ORAS CLI - Add a new command and flag - CLI release process | 2/3 | Yes | Maintained by developers Client Library | - Overview - Golang library guide - API reference - Python library guide | | Yes | Maintained by library developers CLI Reference | This part of content will be generated from the source code of CLI help documentation. | 0 | No | Maintained by developers and PM Glossary | Concepts and terms | 0 | No | Per new terms and features FAQ and Troubleshooting | | 0 | No | According to user questions. Maintained by PM ### Working items - Refactor the documentation structure and layout, remove the redicrect link configuration - Add a new portal for Blogs, migrate the existing content from the documentation portal to Blogs portal - Update the documents [Pushing](https://oras.land/cli/1_pushing/), (Pulling)(https://oras.land/cli/2_pulling/), [Manifest config](https://oras.land/cli/3_manifest_config/) and [Manifest annotations](https://oras.land/cli/4_manifest_annotations/) in the CLI chaprter. They are out-of-date content, so we need to rewrite this chapter using ORAS 0.15.0 - Write new documents with end-to-end scenarios in a chapter > **Suggestions**: > - Download the ORAS CLI 0.15 and test it with each functional flag according to the examples showing in the `--help` > - View the existing content below to understand the typical use cases ### Related references - [ORAS 0.14 blog post](https://oras.land/blog/oras-0.14-and-future/) - ORAS 0.15 blog post (coming soon) - [Push and pull an OCI artifact using an Azure container registry](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-oci-artifacts) - [Push and pull supply chain artifacts using Azure Registry](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-oci-artifacts) ## Ratify There are some basic documents in the [Ratify GitHub](https://github.com/deislabs/ratify/tree/main/docs). The detailed plan needs to be discussed and confirmed with David and Zach. ## Reference W [k Iebsi on the websitete](https://oras.land/) - [Notation website](https://notaryproject.dev/) - [Notary v2 spec](https://github.com/notaryproject/notaryproject) - [Ratify](https://github.com/deislabs/ratify)