Guidelines for Writing Docker Usage Guides

--- title: Guidelines for writing Docker usage guides linkTitle: Write a Docker guide description: Learn how to write guides for learning about Docker, with Docker. ---  This guide provides instructions and best practices for writing tutorial-style usage guides that help users achieve specific goals using Docker. These guides will be featured in the [guides section](/guides/_index.md) of the website, alongside our product manuals and reference materials. Our documentation is written in Markdown, with YAML front matter for metadata. We use [Hugo](https://gohugo.io) to build the website. For more information about how to write content for Docker docs, refer to our [CONTRIBUTING.md](https://github.com/docker/docs/tree/main/CONTRIBUTING.md). ## Purpose of the guides Our usage guides aim to: - Educate users on how to leverage Docker in various contexts. - Provide practical, hands-on experience through step-by-step tutorials. - Help users achieve specific goals relevant to their interests or projects. ## Audience - Experience levels: From beginners to advanced users. - Roles: Developers, system administrators, DevOps engineers, and more. - Technologies: Various programming languages and frameworks. ## Metadata for guides Each guide must include a metadata section at the beginning of the document. This metadata helps users discover and filter guides based on their interests and needs. ### Example metadata format ```yaml --- title: Deploy a machine learning model with Docker linkTitle: Docker for ML deployment description: Learn how to containerize and deploy a machine learning model using Docker. summary: | This guide walks you through the steps to containerize a machine learning model and deploy it using Docker, enabling scalable and portable AI solutions. tags: [machine-learning, deployment] languages: [python] params: time: 30 minutes --- ``` ### Metadata fields - `title` (required): The main title of the guide in sentence case. - `linkTitle` (optional): A shorter title used in navigation menus. - `description` (required): A concise description for SEO purposes. - `summary` (required): A brief overview of the guide's content. - `languages` \* (optional): List of programming languages used. - `tags` \* (optional): Domains or subject areas covered. - `params` - `time` (optional): Estimated reading or completion time. \* Do apply at least one of the `languages` or `tags` taxonomies. The values are used to associate the page with the filter options on the guides landing page. ## Document structure Our guides emphasize learning by doing. Depending on the type of guide, the structure may vary to best suit the content and provide a smooth learning experience. All guides live directly under the `content/guides/` directory in the Docker docs repository. Guides can either be a single page or multiple pages. In the case of multi-page guides, every page is a step in a sequential workflow. If you're creating a single-page guide, create a single markdown file in the guides directory: ```bash # Create the file touch content/guides/my-docker-guide.md # or if you have Hugo installed: hugo new content/guides/my-docker-guide.md ``` To create a multi-page guide, create a directory where each page is a markdown file, with an `_index.md` file representing the introduction to the guide. ```bash # Create the index page for the guide mkdir content/guides/my-docker-guide.md touch content/guides/my-docker-guide/_index.md # or if you have Hugo installed: hugo new content/guides/my-docker-guide/_index.md ``` Then create the pages for the guide under `content/guides/<dir>/<page>.md` as needed. The [metadata](#metadata-for-guides) lives on the `_index.md` page (you don't need to assign metadata to individual pages). ### Guides for specific frameworks or languages For guides that demonstrate how to use Docker with a particular framework or programming language, consider the following outline: 1. **Introduction**

This document provides guidelines for writing Docker usage guides for the Docker website. It covers the purpose of the guides, target audience, metadata requirements, and document structure, including examples and instructions for creating single and multi-page guides. The guides are designed to help users learn how to use Docker through practical, hands-on tutorials.