From 35b4dbf2a042e5ca2159d89b8700431492ba7184 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 3 Oct 2024 15:59:32 +0200 Subject: [PATCH 1/2] hugo: add archetype for guides Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- archetypes/guides.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 archetypes/guides.md diff --git a/archetypes/guides.md b/archetypes/guides.md new file mode 100644 index 00000000000..e92dea73892 --- /dev/null +++ b/archetypes/guides.md @@ -0,0 +1,13 @@ +--- +title: '{{ replace .File.ContentBaseName `-` ` ` | humanize }}' +# linkTitle: A shorter, alternative title +description: # Meta description for SEO. +summary: | # A summary of what's in this guide + In this guide, ... +languages: [] # Programming languages used +products: [] # Docker products involved +levels: [] # Experience level(s) of the intended audience (beginner|intermediate|advanced) +subjects: [] # What's it about? +params: + # time: 10 minutes +--- From 397cd3dc48cc6b233281e2551417a1b796788c98 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 3 Oct 2024 14:35:22 +0200 Subject: [PATCH 2/2] contrib: add guidelines for contributing Docker guides Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/contribute/guides.md | 260 +++++++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 content/contribute/guides.md diff --git a/content/contribute/guides.md b/content/contribute/guides.md new file mode 100644 index 00000000000..ac775387465 --- /dev/null +++ b/content/contribute/guides.md @@ -0,0 +1,260 @@ +--- +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. +languages: [python] +subjects: [machine-learning, deployment] +levels: [intermediate] +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. +- `subjects` (optional): Domains or subject areas covered. +- `levels` (optional): Intended audience experience level (`beginner`, `intermediate`, `advanced`). +- `products` (optional): List of programming languages used. +- `params` + - `time` (optional): Estimated reading or completion time. + +The `languages`, `subjects`, `levels`, and `products` keys are taxonomies, and +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//.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** + - Briefly introduce the framework or language in the context of Docker. + - Explain what the user will achieve by the end of the guide. + - List required software, tools, and knowledge. +2. **Development setup** + - Guide the user through setting up a development environment. + - Include instructions on writing or obtaining sample code. + - Show how to run containers for local development. +3. **Building the application** + - Explain how to create a Dockerfile tailored to the application. + - Provide step-by-step instructions for building the Docker image. + - If applicable, show how to test the application using Docker. +4. **Deploying with Docker** + - Show how to run the application in a Docker container. + - Discuss configuration options and best practices. +5. **Best practices and conclusions** + - Offer tips for optimizing Docker usage with the framework or language. + - Summarize key takeaways, suggest next steps, and further reading. + +### Use-case guides + +For guides focused on accomplishing a specific goal or use case with Docker +(e.g., deploying a machine learning model), use a flexible outline that ensures +a logical flow. + +The following outline is an example. The structure should be adjusted to best +fit the content and ensure a clear, logical progression. Depending on the +subject matter of your use-case guide, the exact structure will vary. + +1. **Introduction** + - Describe the problem or goal. + - Explain the benefits of using Docker in this context. +2. **Prerequisites** + - List required tools, technologies, and prior knowledge. +3. **Setup** + - Provide instructions for setting up the environment. + - Include any necessary configuration steps. +4. **Implementation** + - Walk through the process step by step. + - Use code snippets and explanations to illustrate key points. +5. **Running or deploying the application** + - Guide the user on how to execute or deploy the solution. + - Discuss any verification steps to ensure success. +6. **Conclusion** + - Recap what was achieved. + - Suggest further reading or advanced topics. + +## Example code + +If you create an example repository with source code to accompany your guide, +we strongly encourage you to publish that repository under the +[dockersamples](https://github.com/dockersamples) organization on GitHub. +Publishing your source code under this organization, rather than your personal +account, ensures that the source code remains accessible to the maintainers of +the documentation site after publishing. In the event of a bug or an issue in +the guide, the documentation team can more easily update the guide and its +corresponding example repository. + +Hosting the examples in the official samples namespace also helps secure trust +with users who are reading the guide. + +### Publish a repository under `dockersamples` + +To publish your repository under the `dockersamples` organization, use the +[dockersamples template](https://github.com/dockersamples/sample-app-template) +to initiate a sample repository under your personal namespace. When you've +finished drafting your content and opened your pull request for the +documentation, we can transfer the repository to the dockersamples +organization. + +## Writing style + +Use [sentence case](/contribute/style/formatting.md#capitalization) for all +headings and titles. This means only the first word and proper nouns are +capitalized. + +### Voice and tone + +- **Clarity and conciseness**: Use simple language and short sentences to convey information effectively. +- **Active voice**: Write in the active voice to engage the reader (e.g., "Run the command" instead of "The command should be run"). +- **Consistency**: Maintain a consistent tone and terminology throughout the guide. + +For detailed guidelines, refer to our [voice and tone documentation](/contribute/style/voice-tone.md). + +### Formatting conventions + +- **Headings**: Use H2 for main sections and H3 for subsections, following sentence case. +- **Code examples**: Provide complete, working code snippets with syntax highlighting. +- **Lists and steps**: Use numbered lists for sequential steps and bullet points for non-sequential information. +- **Emphasis**: Use bold for UI elements (e.g., **Button**), and italics for emphasis. +- **Links**: Use descriptive link text (e.g., [Install Docker](/get-started/get-docker.md)). + +For more details, see our [content formatting guidelines](/contribute/style/formatting.md) +and [grammar and style rules](/contribute/style/grammar.md). + +## Best practices + +- **Test all instructions** + - Ensure all code and commands work as expected. + - Verify that the guide can be followed successfully from start to finish. +- **Relevance** + - Focus on real-world applications and scenarios. + - Keep the content up-to-date with the latest Docker versions. +- **Troubleshooting tips** + - Anticipate common issues and provide solutions or references. +- **Visual aids** + - Include screenshots or diagrams where they enhance understanding. + - Add captions and alt text for accessibility. +- **Third-party tools** + - Avoid requiring the user to install third-party tools or modify their local development environment. + - Prefer using containerized tools and methods where applicable (e.g. `docker exec`). + - Some tools are reasonable to assume as installed or prerequisites for guides, such as Node.js and npm. Use your better judgement. + +## Additional resources + +- **Existing guides** + - Refer to [Docker Guides](/guides/_index.md) for examples and inspiration. +- **Style guides** + - [Voice and tone](/contribute/style/voice-tone.md) + - [Content formatting](/contribute/style/formatting.md) + - [Grammar and style](/contribute/style/grammar.md) + +## Submission process + +- **Proposal** + - Raise an issue on the [Docker documentation GitHub repository](https://github.com/docker/docs) + with a request to add a new guide. + - Once the proposal has been accepted, start writing your guide by forking + the repository and creating a branch for your work. + + > [!NOTE] + > Avoid contributing from the `main` branch of your fork, since it makes it + > more difficult for maintainers to help you fix any issues that may arise. + +- **Review** + - Proofread your guide for grammar, clarity, and adherence to the guidelines. + - Once your draft is ready, raise a pull request, with a reference to the + original issue. + - The Docker documentation team and subject matter experts will review your + submission and provide feedback on the pull request directly. +- **Publishing** + - Your guide will be published on the Docker documentation website when the + reviewers have approved and merged your pull request. + +Thank you for contributing to the Docker community. Your expertise helps users +worldwide harness the power of Docker.