Skip to content

Commit 1c61f93

Browse files
dvdksndvdksn
authored
Merge pull request #21052 from dvdksn/contribute-guides
contrib: add guidelines for contributing Docker guides
2 parents 2478e67 + 397cd3d commit 1c61f93

File tree

2 files changed

+273
-0
lines changed

2 files changed

+273
-0
lines changed

‎archetypes/guides.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: '{{ replace .File.ContentBaseName `-` ` ` | humanize }}'
3+
# linkTitle: A shorter, alternative title
4+
description: # Meta description for SEO.
5+
summary: | # A summary of what's in this guide
6+
In this guide, ...
7+
languages: [] # Programming languages used
8+
products: [] # Docker products involved
9+
levels: [] # Experience level(s) of the intended audience (beginner|intermediate|advanced)
10+
subjects: [] # What's it about?
11+
params:
12+
# time: 10 minutes
13+
---

‎content/contribute/guides.md‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
---
2+
title: Guidelines for writing Docker usage guides
3+
linkTitle: Write a Docker guide
4+
description: Learn how to write guides for learning about Docker, with Docker.
5+
---
6+
7+
<!-- vale Docker.We = NO -->
8+
9+
This guide provides instructions and best practices for writing tutorial-style
10+
usage guides that help users achieve specific goals using Docker. These guides
11+
will be featured in the [guides section](/guides/_index.md) of the website,
12+
alongside our product manuals and reference materials.
13+
14+
Our documentation is written in Markdown, with YAML front matter for metadata.
15+
We use [Hugo](https://gohugo.io) to build the website. For more information
16+
about how to write content for Docker docs, refer to our
17+
[CONTRIBUTING.md](https://github.com/docker/docs/tree/main/CONTRIBUTING.md).
18+
19+
## Purpose of the guides
20+
21+
Our usage guides aim to:
22+
23+
- Educate users on how to leverage Docker in various contexts.
24+
- Provide practical, hands-on experience through step-by-step tutorials.
25+
- Help users achieve specific goals relevant to their interests or projects.
26+
27+
## Audience
28+
29+
- Experience levels: From beginners to advanced users.
30+
- Roles: Developers, system administrators, DevOps engineers, and more.
31+
- Technologies: Various programming languages and frameworks.
32+
33+
## Metadata for guides
34+
35+
Each guide must include a metadata section at the beginning of the document.
36+
This metadata helps users discover and filter guides based on their interests
37+
and needs.
38+
39+
### Example metadata format
40+
41+
```yaml
42+
---
43+
title: Deploy a machine learning model with Docker
44+
linkTitle: Docker for ML deployment
45+
description: Learn how to containerize and deploy a machine learning model using Docker.
46+
summary: |
47+
This guide walks you through the steps to containerize a machine learning
48+
model and deploy it using Docker, enabling scalable and portable AI
49+
solutions.
50+
languages: [python]
51+
subjects: [machine-learning, deployment]
52+
levels: [intermediate]
53+
params:
54+
time: 30 minutes
55+
---
56+
```
57+
58+
### Metadata fields
59+
60+
- `title` (required): The main title of the guide in sentence case.
61+
- `linkTitle` (optional): A shorter title used in navigation menus.
62+
- `description` (required): A concise description for SEO purposes.
63+
- `summary` (required): A brief overview of the guide's content.
64+
- `languages` (optional): List of programming languages used.
65+
- `subjects` (optional): Domains or subject areas covered.
66+
- `levels` (optional): Intended audience experience level (`beginner`, `intermediate`, `advanced`).
67+
- `products` (optional): List of programming languages used.
68+
- `params`
69+
- `time` (optional): Estimated reading or completion time.
70+
71+
The `languages`, `subjects`, `levels`, and `products` keys are taxonomies, and
72+
the values are used to associate the page with the filter options on the guides
73+
landing page.
74+
75+
## Document structure
76+
77+
Our guides emphasize learning by doing. Depending on the type of guide, the
78+
structure may vary to best suit the content and provide a smooth learning
79+
experience.
80+
81+
All guides live directly under the `content/guides/` directory in the Docker
82+
docs repository. Guides can either be a single page or multiple pages. In the
83+
case of multi-page guides, every page is a step in a sequential workflow.
84+
85+
If you're creating a single-page guide, create a single markdown file in the
86+
guides directory:
87+
88+
```bash
89+
# Create the file
90+
touch content/guides/my-docker-guide.md
91+
# or if you have Hugo installed:
92+
hugo new content/guides/my-docker-guide.md
93+
```
94+
95+
To create a multi-page guide, create a directory where each page is a markdown
96+
file, with an `_index.md` file representing the introduction to the guide.
97+
98+
```bash
99+
# Create the index page for the guide
100+
mkdir content/guides/my-docker-guide.md
101+
touch content/guides/my-docker-guide/_index.md
102+
# or if you have Hugo installed:
103+
hugo new content/guides/my-docker-guide/_index.md
104+
```
105+
106+
Then create the pages for the guide under `content/guides/<dir>/<page>.md` as
107+
needed. The [metadata](#metadata-for-guides) lives on the `_index.md` page (you
108+
don't need to assign metadata to individual pages).
109+
110+
### Guides for specific frameworks or languages
111+
112+
For guides that demonstrate how to use Docker with a particular framework or
113+
programming language, consider the following outline:
114+
115+
1. **Introduction**
116+
- Briefly introduce the framework or language in the context of Docker.
117+
- Explain what the user will achieve by the end of the guide.
118+
- List required software, tools, and knowledge.
119+
2. **Development setup**
120+
- Guide the user through setting up a development environment.
121+
- Include instructions on writing or obtaining sample code.
122+
- Show how to run containers for local development.
123+
3. **Building the application**
124+
- Explain how to create a Dockerfile tailored to the application.
125+
- Provide step-by-step instructions for building the Docker image.
126+
- If applicable, show how to test the application using Docker.
127+
4. **Deploying with Docker**
128+
- Show how to run the application in a Docker container.
129+
- Discuss configuration options and best practices.
130+
5. **Best practices and conclusions**
131+
- Offer tips for optimizing Docker usage with the framework or language.
132+
- Summarize key takeaways, suggest next steps, and further reading.
133+
134+
### Use-case guides
135+
136+
For guides focused on accomplishing a specific goal or use case with Docker
137+
(e.g., deploying a machine learning model), use a flexible outline that ensures
138+
a logical flow.
139+
140+
The following outline is an example. The structure should be adjusted to best
141+
fit the content and ensure a clear, logical progression. Depending on the
142+
subject matter of your use-case guide, the exact structure will vary.
143+
144+
1. **Introduction**
145+
- Describe the problem or goal.
146+
- Explain the benefits of using Docker in this context.
147+
2. **Prerequisites**
148+
- List required tools, technologies, and prior knowledge.
149+
3. **Setup**
150+
- Provide instructions for setting up the environment.
151+
- Include any necessary configuration steps.
152+
4. **Implementation**
153+
- Walk through the process step by step.
154+
- Use code snippets and explanations to illustrate key points.
155+
5. **Running or deploying the application**
156+
- Guide the user on how to execute or deploy the solution.
157+
- Discuss any verification steps to ensure success.
158+
6. **Conclusion**
159+
- Recap what was achieved.
160+
- Suggest further reading or advanced topics.
161+
162+
## Example code
163+
164+
If you create an example repository with source code to accompany your guide,
165+
we strongly encourage you to publish that repository under the
166+
[dockersamples](https://github.com/dockersamples) organization on GitHub.
167+
Publishing your source code under this organization, rather than your personal
168+
account, ensures that the source code remains accessible to the maintainers of
169+
the documentation site after publishing. In the event of a bug or an issue in
170+
the guide, the documentation team can more easily update the guide and its
171+
corresponding example repository.
172+
173+
Hosting the examples in the official samples namespace also helps secure trust
174+
with users who are reading the guide.
175+
176+
### Publish a repository under `dockersamples`
177+
178+
To publish your repository under the `dockersamples` organization, use the
179+
[dockersamples template](https://github.com/dockersamples/sample-app-template)
180+
to initiate a sample repository under your personal namespace. When you've
181+
finished drafting your content and opened your pull request for the
182+
documentation, we can transfer the repository to the dockersamples
183+
organization.
184+
185+
## Writing style
186+
187+
Use [sentence case](/contribute/style/formatting.md#capitalization) for all
188+
headings and titles. This means only the first word and proper nouns are
189+
capitalized.
190+
191+
### Voice and tone
192+
193+
- **Clarity and conciseness**: Use simple language and short sentences to convey information effectively.
194+
- **Active voice**: Write in the active voice to engage the reader (e.g., "Run the command" instead of "The command should be run").
195+
- **Consistency**: Maintain a consistent tone and terminology throughout the guide.
196+
197+
For detailed guidelines, refer to our [voice and tone documentation](/contribute/style/voice-tone.md).
198+
199+
### Formatting conventions
200+
201+
- **Headings**: Use H2 for main sections and H3 for subsections, following sentence case.
202+
- **Code examples**: Provide complete, working code snippets with syntax highlighting.
203+
- **Lists and steps**: Use numbered lists for sequential steps and bullet points for non-sequential information.
204+
- **Emphasis**: Use bold for UI elements (e.g., **Button**), and italics for emphasis.
205+
- **Links**: Use descriptive link text (e.g., [Install Docker](/get-started/get-docker.md)).
206+
207+
For more details, see our [content formatting guidelines](/contribute/style/formatting.md)
208+
and [grammar and style rules](/contribute/style/grammar.md).
209+
210+
## Best practices
211+
212+
- **Test all instructions**
213+
- Ensure all code and commands work as expected.
214+
- Verify that the guide can be followed successfully from start to finish.
215+
- **Relevance**
216+
- Focus on real-world applications and scenarios.
217+
- Keep the content up-to-date with the latest Docker versions.
218+
- **Troubleshooting tips**
219+
- Anticipate common issues and provide solutions or references.
220+
- **Visual aids**
221+
- Include screenshots or diagrams where they enhance understanding.
222+
- Add captions and alt text for accessibility.
223+
- **Third-party tools**
224+
- Avoid requiring the user to install third-party tools or modify their local development environment.
225+
- Prefer using containerized tools and methods where applicable (e.g. `docker exec`).
226+
- Some tools are reasonable to assume as installed or prerequisites for guides, such as Node.js and npm. Use your better judgement.
227+
228+
## Additional resources
229+
230+
- **Existing guides**
231+
- Refer to [Docker Guides](/guides/_index.md) for examples and inspiration.
232+
- **Style guides**
233+
- [Voice and tone](/contribute/style/voice-tone.md)
234+
- [Content formatting](/contribute/style/formatting.md)
235+
- [Grammar and style](/contribute/style/grammar.md)
236+
237+
## Submission process
238+
239+
- **Proposal**
240+
- Raise an issue on the [Docker documentation GitHub repository](https://github.com/docker/docs)
241+
with a request to add a new guide.
242+
- Once the proposal has been accepted, start writing your guide by forking
243+
the repository and creating a branch for your work.
244+
245+
> [!NOTE]
246+
> Avoid contributing from the `main` branch of your fork, since it makes it
247+
> more difficult for maintainers to help you fix any issues that may arise.
248+
249+
- **Review**
250+
- Proofread your guide for grammar, clarity, and adherence to the guidelines.
251+
- Once your draft is ready, raise a pull request, with a reference to the
252+
original issue.
253+
- The Docker documentation team and subject matter experts will review your
254+
submission and provide feedback on the pull request directly.
255+
- **Publishing**
256+
- Your guide will be published on the Docker documentation website when the
257+
reviewers have approved and merged your pull request.
258+
259+
Thank you for contributing to the Docker community. Your expertise helps users
260+
worldwide harness the power of Docker.

0 commit comments

Comments
 (0)