mirror of
https://github.com/docker/docs.git
synced 2026-04-05 10:48:55 +07:00
986 lines
40 KiB
HTML
986 lines
40 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
|
||
|
||
<meta name="docker_version" content="1.4.1">
|
||
<meta name="docker_git_branch" content="master">
|
||
<meta name="docker_git_commit" content="3c097c2">
|
||
<meta name="docker_build_date" content="Wed Jan 28 04:30:29 UTC 2015">
|
||
|
||
<meta name="description" content="Style guide for Docker documentation describing standards and conventions for contributors">
|
||
<meta name="keywords" content="style, guide, docker, documentation">
|
||
|
||
<link rel="canonical" href="/contributing/docs_style-guide/">
|
||
<link href="/css/bootstrap-custom.css" rel="stylesheet">
|
||
<link href="/css/main.css" rel="stylesheet">
|
||
<link href="/css/prettify-1.0.css" rel="stylesheet">
|
||
<link rel="stylesheet" type="text/css" href="/css/dockerfile_tutorial.css">
|
||
<link href="/tipuesearch/tipuesearch.css" rel="stylesheet">
|
||
<link href="/css/docs.css" rel="stylesheet">
|
||
<link rel="shortcut icon" href="/img/favicon.png">
|
||
<title>Documentation style guide - Docker Documentation</title>
|
||
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
|
||
<!--[if lt IE 9]>
|
||
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
|
||
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
|
||
<![endif]-->
|
||
|
||
<script type="text/javascript">
|
||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
||
ga('create', 'UA-6096819-11', 'docker.com');
|
||
ga('require', 'linkid', 'linkid.js');
|
||
ga('send', 'pageview', {
|
||
'page': location.pathname + location.search + location.hash,
|
||
});
|
||
</script>
|
||
|
||
</head>
|
||
<body>
|
||
|
||
<div id="topmostnav" class="topmostnav_loggedout navbar navbar-static-top public">
|
||
<div class="container">
|
||
<a href="http://www.docker.com/" title="Homepage">
|
||
<div class="brand logo"><img src="/img/nav/docker-logo-loggedout.png"> </div>
|
||
</a>
|
||
<ul class="nav">
|
||
<li class=""><a href="http://www.docker.com/whatisdocker/" title="What is Docker">What is Docker?</a></li>
|
||
<li class=""><a href="http://www.docker.com/resources/usecases/" title="Use Cases">Use Cases</a></li>
|
||
<li class=""><a href="http://www.docker.com/tryit/" title="Try It!">Try It!</a></li>
|
||
<li class="active"><a href="https://docs.docker.com" title="Install & Docs">Install & Docs</a></li>
|
||
<li><a href="https://registry.hub.docker.com" title="Browse">Browse</a></li>
|
||
</ul>
|
||
<div id="usernav" class="pull-right">
|
||
<a href="https://hub.docker.com/account/login" class="btn nav-button2" title="Lg In">Log In</a>
|
||
<a href="https://hub.docker.com/account/signup" class="btn nav-button1" title="Sign Up">Sign Up</a>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div id="topmostnav" class="topmostnav_loggedin navbar navbar-static-top">
|
||
<div class="container">
|
||
<a href="http://www.docker.com/" title="Docker Docs Home"><div class="brand logo"><img src="/img/nav/docker-logo-loggedin.png"> </div></a>
|
||
<form id="search_box_header" class="navbar-index-search pull-right" action="https://registry.hub.docker.com/search">
|
||
<span role="status" aria-live="polite" class="ui-helper-hidden-accessible"></span><input type="text" class="search-query ui-autocomplete-input" placeholder="Search..." name="q" value="" autocomplete="off">
|
||
</form>
|
||
<ul class="nav">
|
||
<li><a href="https://registry.hub.docker.com" title="Browse Repos">Browse Repos</a></li>
|
||
<li class="active"><a href="http://docs.docker.com" title="Documentation">Documentation</a></li>
|
||
<li><a href="http://www.docker.com/community/participate/" title="Community">Community</a></li>
|
||
<li><a href="http://www.docker.com/resources/help/" title="Help">Help</a></li>
|
||
</ul>
|
||
<div id="usernav" class="pull-right">
|
||
<ul class="nav user">
|
||
<li class="dropdown">
|
||
<a id="logged-in-header-username" class="dropdown-toggle" data-toggle="dropdown" href="#">
|
||
<img class="profile" src="" alt="profile picture">
|
||
</a>
|
||
<ul class="dropdown-menu pull-right">
|
||
<li><a href="https://hub.docker.com/">View Profile</a></li>
|
||
<li><a href="https://hub.docker.com/account/settings/">Settings</a></li>
|
||
<li><a href="https://hub.docker.com/repos/">My Repositories</a></li>
|
||
<li><a href="https://hub.docker.com/plans/billing-info">Billing</a></li>
|
||
<li><a href="https://hub.docker.com/account/logout/?next=/">Log out</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="wrap">
|
||
<nav id="nav_menu" class="clearfix navbar navbar-default navbar-static-top affix" role="navigation">
|
||
<div id="docsnav">
|
||
<ul id="main-nav" class="pull-left">
|
||
|
||
|
||
<li class="dd_menu pull-left">
|
||
|
||
<a href="/">About</a>
|
||
|
||
<ul class="dd_submenu" style="max-height: 75px;">
|
||
|
||
<li >
|
||
<a href="/">Docker</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/release-notes/">Release Notes</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/introduction/understanding-docker/">Understanding Docker</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
|
||
<li class="dd_menu pull-left">
|
||
|
||
<a href="/installation/mac/">Installation</a>
|
||
|
||
<ul class="dd_submenu" style="max-height: 75px;">
|
||
|
||
<li >
|
||
<a href="/installation/mac/">Mac OS X</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/ubuntulinux/">Ubuntu</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/rhel/">Red Hat Enterprise Linux</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/oracle/">Oracle Linux</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/centos/">CentOS</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/debian/">Debian</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/gentoolinux/">Gentoo</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/google/">Google Cloud Platform</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/rackspace/">Rackspace Cloud</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/amazon/">Amazon EC2</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/softlayer/">IBM Softlayer</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/archlinux/">Arch Linux</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/frugalware/">FrugalWare</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/fedora/">Fedora</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/SUSE/">SUSE</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/cruxlinux/">CRUX Linux</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/windows/">Microsoft Windows</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/installation/binaries/">Binaries</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
|
||
<li class="dd_menu pull-left">
|
||
|
||
<a href="/userguide/">User Guide</a>
|
||
|
||
<ul class="dd_submenu" style="max-height: 75px;">
|
||
|
||
<li >
|
||
<a href="/userguide/">The Docker User Guide</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/userguide/dockerhub/">Getting Started with Docker Hub</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/userguide/dockerizing/">Dockerizing Applications</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/userguide/usingdocker/">Working with Containers</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/userguide/dockerimages/">Working with Docker Images</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/userguide/dockerlinks/">Linking containers together</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/userguide/dockervolumes/">Managing data in containers</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/userguide/dockerrepos/">Working with Docker Hub</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
|
||
<li class="dd_menu pull-left">
|
||
|
||
<a href="/docker-hub/">Docker Hub</a>
|
||
|
||
<ul class="dd_submenu" style="max-height: 75px;">
|
||
|
||
<li >
|
||
<a href="/docker-hub/">Docker Hub</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/docker-hub/accounts/">Accounts</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/docker-hub/repos/">Repositories</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/docker-hub/builds/">Automated Builds</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/docker-hub/official_repos/">Official Repo Guidelines</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
|
||
<li class="dd_menu pull-left">
|
||
|
||
<a href="/examples/nodejs_web_app/">Examples</a>
|
||
|
||
<ul class="dd_submenu" style="max-height: 75px;">
|
||
|
||
<li >
|
||
<a href="/examples/nodejs_web_app/">Dockerizing a Node.js web application</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/examples/mongodb/">Dockerizing MongoDB</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/examples/running_redis_service/">Dockerizing a Redis service</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/examples/postgresql_service/">Dockerizing a PostgreSQL service</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/examples/running_riak_service/">Dockerizing a Riak service</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/examples/running_ssh_service/">Dockerizing an SSH service</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/examples/couchdb_data_volumes/">Dockerizing a CouchDB service</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/examples/apt-cacher-ng/">Dockerizing an Apt-Cacher-ng service</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
|
||
<li class="dd_menu pull-left">
|
||
|
||
<a href="/articles/basics/">Articles</a>
|
||
|
||
<ul class="dd_submenu" style="max-height: 75px;">
|
||
|
||
<li >
|
||
<a href="/articles/basics/">Docker basics</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/networking/">Advanced networking</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/security/">Security</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/https/">Running Docker with HTTPS</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/registry_mirror/">Run a local registry mirror</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/host_integration/">Automatically starting containers</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/baseimages/">Creating a base image</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/dockerfile_best-practices/">Best practices for writing Dockerfiles</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/certificates/">Using certificates for repository client verification</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/using_supervisord/">Using Supervisor</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/cfengine_process_management/">Process management with CFEngine</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/puppet/">Using Puppet</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/chef/">Using Chef</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/dsc/">Using PowerShell DSC</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/ambassador_pattern_linking/">Cross-Host linking using ambassador containers</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/runmetrics/">Runtime metrics</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/b2d_volume_resize/">Increasing a Boot2Docker volume</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/articles/systemd/">Controlling and configuring Docker using Systemd</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
|
||
<li class="dd_menu pull-left">
|
||
|
||
<a href="/reference/commandline/cli/">Reference</a>
|
||
|
||
<ul class="dd_submenu" style="max-height: 75px;">
|
||
|
||
<li >
|
||
<a href="/reference/commandline/cli/">Command line</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/builder/">Dockerfile</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/faq/">FAQ</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/run/">Run Reference</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/docker-io_api/">Docker Hub API</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/registry_api/">Docker Registry API</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/registry_api_client_libraries/">Docker Registry API Client Libraries</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/hub_registry_spec/">Docker Hub and Registry Spec</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/docker_remote_api/">Docker Remote API</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/docker_remote_api_v1.16/">Docker Remote API v1.16</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/docker_remote_api_v1.15/">Docker Remote API v1.15</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/docker_remote_api_v1.14/">Docker Remote API v1.14</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/docker_remote_api_v1.13/">Docker Remote API v1.13</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/docker_remote_api_v1.12/">Docker Remote API v1.12</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/docker_remote_api_v1.11/">Docker Remote API v1.11</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/remote_api_client_libraries/">Docker Remote API Client Libraries</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/reference/api/docker_io_accounts_api/">Docker Hub Accounts API</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
|
||
<li class="dd_menu pull-left active">
|
||
|
||
<a href="/contributing/contributing/">Contribute</a>
|
||
|
||
<ul class="dd_submenu" style="max-height: 75px;">
|
||
|
||
<li >
|
||
<a href="/contributing/contributing/">Contributing</a>
|
||
</li>
|
||
|
||
<li >
|
||
<a href="/contributing/devenvironment/">Development environment</a>
|
||
</li>
|
||
|
||
<li class="active">
|
||
<a href="/contributing/docs_style-guide/">Documentation style guide</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
</ul>
|
||
<form id="nav_search" class="pull-right" action="/jsearch/">
|
||
<span role="status" aria-live="polite" class="ui-helper-hidden-accessible"></span>
|
||
<input name="q" id="tipue_search_input" type="text" class="search_input search-query ui-autocomplete-input" placeholder="Search the Docs" autocomplete="off">
|
||
</form>
|
||
</div>
|
||
</nav>
|
||
<div id="content" class="container">
|
||
<div class="row">
|
||
|
||
<div class="span3" id="leftnav">
|
||
<div id="toc_table">
|
||
<ul class="nav nav-tabs nav-stacked">
|
||
|
||
|
||
<li class=""><a href="#style-standards">Style standards</a></li>
|
||
|
||
<h3><a href="#prose-style">Prose style</a></h3>
|
||
|
||
<h3><a href="#metaphor-and-figurative-language">Metaphor and figurative language</a></h3>
|
||
|
||
|
||
<li class=""><a href="#specific-conventions">Specific conventions</a></li>
|
||
|
||
<h3><a href="#contractions">Contractions</a></h3>
|
||
|
||
<h3><a href="#use-of-dashes-in-a-sentence">Use of dashes in a sentence.</a></h3>
|
||
|
||
<h3><a href="#pronouns">Pronouns</a></h3>
|
||
|
||
<h3><a href="#capitalization">Capitalization</a></h3>
|
||
|
||
|
||
<li class=""><a href="#periods">Periods</a></li>
|
||
|
||
<h3><a href="#abbreviations-and-acronyms">Abbreviations and acronyms</a></h3>
|
||
|
||
<h3><a href="#lists">Lists</a></h3>
|
||
|
||
<h3><a href="#numbers">Numbers</a></h3>
|
||
|
||
<h3><a href="#notes">Notes</a></h3>
|
||
|
||
<h3><a href="#avoid-excess-use-of-ie">Avoid excess use of "i.e."</a></h3>
|
||
|
||
<h3><a href="#preferred-usages">Preferred usages</a></h3>
|
||
|
||
<h3><a href="#oxford-comma">Oxford comma</a></h3>
|
||
|
||
<h3><a href="#code-and-ui-text-styling">Code and UI text styling</a></h3>
|
||
|
||
|
||
<li class=""><a href="#pull-requests">Pull requests</a></li>
|
||
|
||
<h3><a href="#commit-messages">Commit messages</a></h3>
|
||
|
||
|
||
<li class=""><a href="#links">Links</a></li>
|
||
|
||
|
||
<li class=""><a href="#graphics">Graphics</a></li>
|
||
|
||
|
||
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div class="span9 content-body">
|
||
|
||
|
||
|
||
<div id="versionnav" class="span3 pull-right">
|
||
<ul class="nav version pull-right">
|
||
<li class="dropdown">
|
||
<a id="document-version-number" class="dropdown-toggle" data-toggle="dropdown" href="#">
|
||
Version v1.4
|
||
</a>
|
||
<ul id="documentation-version-list" class="dropdown-menu pull-right">
|
||
|
||
<li role="presentation" class="divider"></li>
|
||
<li> <a class="home-link3 tertiary-nav" href="https://github.com/docker/docker/blob/master/docs/sources/contributing/docs_style-guide.md" >Edit on GitHub</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h1 id="docker-documentation-style-grammar-conventions">Docker documentation: style & grammar conventions</h1>
|
||
<h2 id="style-standards">Style standards</h2>
|
||
<p>Over time, different publishing communities have written standards for the style
|
||
and grammar they prefer in their publications. These standards are called
|
||
<a href="http://en.wikipedia.org/wiki/Style_guide">style guides</a>. Generally, Docker’s
|
||
documentation uses the standards described in the
|
||
<a href="http://en.wikipedia.org/wiki/AP_Stylebook">Associated Press's (AP) style guide</a>.
|
||
If a question about syntactical, grammatical, or lexical practice comes up,
|
||
refer to the AP guide first. If you don’t have a copy of (or online subscription
|
||
to) the AP guide, you can almost always find an answer to a specific question by
|
||
searching the web. If you can’t find an answer, please ask a
|
||
<a href="https://github.com/docker/docker/blob/master/docs/MAINTAINERS">maintainer</a> and
|
||
we will find the answer.</p>
|
||
<p>That said, please don't get too hung up on using correct style. We'd rather have
|
||
you submit good information that doesn't conform to the guide than no
|
||
information at all. Docker's tech writers are always happy to help you with the
|
||
prose, and we promise not to judge or use a red pen!</p>
|
||
<blockquote>
|
||
<p><strong>Note:</strong>
|
||
The documentation is written with paragraphs wrapped at 80 column lines to
|
||
make it easier for terminal use. You can probably set up your favorite text
|
||
editor to do this automatically for you.</p>
|
||
</blockquote>
|
||
<h3 id="prose-style">Prose style</h3>
|
||
<p>In general, try to write simple, declarative prose. We prefer short,
|
||
single-clause sentences and brief three-to-five sentence paragraphs. Try to
|
||
choose vocabulary that is straightforward and precise. Avoid creating new terms,
|
||
using obscure terms or, in particular, using a lot of jargon. For example, use
|
||
"use" instead of leveraging "leverage".</p>
|
||
<p>That said, don’t feel like you have to write for localization or for
|
||
English-as-a-second-language (ESL) speakers specifically. Assume you are writing
|
||
for an ordinary speaker of English with a basic university education. If your
|
||
prose is simple, clear, and straightforward it will translate readily.</p>
|
||
<p>One way to think about this is to assume Docker’s users are generally university
|
||
educated and read at at least a "16th" grade level (meaning they have a
|
||
university degree). You can use a <a href="https://readability-score.com/">readability
|
||
tester</a> to help guide your judgement. For
|
||
example, the readability score for the phrase "Containers should be ephemeral"
|
||
is around the 13th grade level (first year at university), and so is acceptable.</p>
|
||
<p>In all cases, we prefer clear, concise communication over stilted, formal
|
||
language. Don't feel like you have to write documentation that "sounds like
|
||
technical writing."</p>
|
||
<h3 id="metaphor-and-figurative-language">Metaphor and figurative language</h3>
|
||
<p>One exception to the "don’t write directly for ESL" rule is to avoid the use of
|
||
metaphor or other
|
||
<a href="http://en.wikipedia.org/wiki/Literal_and_figurative_language">figurative language</a> to
|
||
describe things. There are too many cultural and social issues that can prevent
|
||
a reader from correctly interpreting a metaphor.</p>
|
||
<h2 id="specific-conventions">Specific conventions</h2>
|
||
<p>Below are some specific recommendations (and a few deviations) from AP style
|
||
that we use in our docs.</p>
|
||
<h3 id="contractions">Contractions</h3>
|
||
<p>As long as your prose does not become too slangy or informal, it's perfectly
|
||
acceptable to use contractions in our documentation. Make sure to use
|
||
apostrophes correctly.</p>
|
||
<h3 id="use-of-dashes-in-a-sentence">Use of dashes in a sentence.</h3>
|
||
<p>Dashes refers to the en dash (–) and the em dash (—). Dashes can be used to
|
||
separate parenthetical material.</p>
|
||
<p>Usage Example: This is an example of a Docker client – which uses the Big Widget
|
||
to run – and does x, y, and z.</p>
|
||
<p>Use dashes cautiously and consider whether commas or parentheses would work just
|
||
as well. We always emphasize short, succinct sentences.</p>
|
||
<p>More info from the always handy <a href="http://www.quickanddirtytips.com/education/grammar/dashes-parentheses-and-commas">Grammar Girl site</a>.</p>
|
||
<h3 id="pronouns">Pronouns</h3>
|
||
<p>It's okay to use first and second person pronouns. Specifically, use "we" to
|
||
refer to Docker and "you" to refer to the user. For example, "We built the
|
||
<code>exec</code> command so you can resize a TTY session."</p>
|
||
<p>As much as possible, avoid using gendered pronouns ("he" and "she", etc.).
|
||
Either recast the sentence so the pronoun is not needed or, less preferably,
|
||
use "they" instead. If you absolutely can't get around using a gendered pronoun,
|
||
pick one and stick to it. Which one you choose is up to you. One common
|
||
convention is to use the pronoun of the author's gender, but if you prefer to
|
||
default to "he" or "she", that's fine too.</p>
|
||
<h3 id="capitalization">Capitalization</h3>
|
||
<h4 id="in-general">In general</h4>
|
||
<p>Only proper nouns should be capitalized in body text. In general, strive to be
|
||
as strict as possible in applying this rule. Avoid using capitals for emphasis
|
||
or to denote "specialness".</p>
|
||
<p>The word "Docker" should always be capitalized when referring to either the
|
||
company or the technology. The only exception is when the term appears in a code
|
||
sample.</p>
|
||
<h4 id="starting-sentences">Starting sentences</h4>
|
||
<p>Because code samples should always be written exactly as they would appear
|
||
on-screen, you should avoid starting sentences with a code sample.</p>
|
||
<h4 id="in-headings">In headings</h4>
|
||
<p>Headings take sentence capitalization, meaning that only the first letter is
|
||
capitalized (and words that would normally be capitalized in a sentence, e.g.,
|
||
"Docker"). Do not use Title Case (i.e., capitalizing every word) for headings. Generally, we adhere to <a href="http://www.quickanddirtytips.com/education/grammar/capitalizing-titles">AP style
|
||
for titles</a>.</p>
|
||
<h2 id="periods">Periods</h2>
|
||
<p>We prefer one space after a period at the end of a sentence, not two. </p>
|
||
<p>See <a href="#lists">lists</a> below for how to punctuate list items.</p>
|
||
<h3 id="abbreviations-and-acronyms">Abbreviations and acronyms</h3>
|
||
<ul>
|
||
<li>
|
||
<p>Exempli gratia (e.g.) and id est ( i.e.): these should always have periods and
|
||
are always followed by a comma.</p>
|
||
</li>
|
||
<li>
|
||
<p>Acronyms are pluralized by simply adding "s", e.g., PCs, OSs.</p>
|
||
</li>
|
||
<li>
|
||
<p>On first use on a given page, the complete term should be used, with the
|
||
abbreviation or acronym in parentheses. E.g., Red Hat Enterprise Linux (RHEL).
|
||
The exception is common, non-technical acronyms like AKA or ASAP. Note that
|
||
acronyms other than i.e. and e.g. are capitalized.</p>
|
||
</li>
|
||
<li>
|
||
<p>Other than "e.g." and "i.e." (as discussed above), acronyms do not take
|
||
periods, PC not P.C.</p>
|
||
</li>
|
||
</ul>
|
||
<h3 id="lists">Lists</h3>
|
||
<p>When writing lists, keep the following in mind:</p>
|
||
<p>Use bullets when the items being listed are independent of each other and the
|
||
order of presentation is not important.</p>
|
||
<p>Use numbers for steps that have to happen in order or if you have mentioned the
|
||
list in introductory text. For example, if you wrote "There are three config
|
||
settings available for SSL, as follows:", you would number each config setting
|
||
in the subsequent list.</p>
|
||
<p>In all lists, if an item is a complete sentence, it should end with a
|
||
period. Otherwise, we prefer no terminal punctuation for list items.
|
||
Each item in a list should start with a capital.</p>
|
||
<h3 id="numbers">Numbers</h3>
|
||
<p>Write out numbers in body text and titles from one to ten. From 11 on, use numerals.</p>
|
||
<h3 id="notes">Notes</h3>
|
||
<p>Use notes sparingly and only to bring things to the reader's attention that are
|
||
critical or otherwise deserving of being called out from the body text. Please
|
||
format all notes as follows:</p>
|
||
<pre class="prettyprint well"><code>> **Note:**
|
||
> One line of note text
|
||
> another line of note text
|
||
</code></pre>
|
||
<h3 id="avoid-excess-use-of-ie">Avoid excess use of "i.e."</h3>
|
||
<p>Minimize your use of "i.e.". It can add an unnecessary interpretive burden on
|
||
the reader. Avoid writing "This is a thing, i.e., it is like this". Just
|
||
say what it is: "This thing is …"</p>
|
||
<h3 id="preferred-usages">Preferred usages</h3>
|
||
<h4 id="login-vs-log-in">Login vs. log in.</h4>
|
||
<p>A "login" is a noun (one word), as in "Enter your login". "Log in" is a compound
|
||
verb (two words), as in "Log in to the terminal".</p>
|
||
<h3 id="oxford-comma">Oxford comma</h3>
|
||
<p>One way in which we differ from AP style is that Docker’s docs use the <a href="http://en.wikipedia.org/wiki/Serial_comma">Oxford
|
||
comma</a> in all cases. That’s our
|
||
position on this controversial topic, we won't change our mind, and that’s that!</p>
|
||
<h3 id="code-and-ui-text-styling">Code and UI text styling</h3>
|
||
<p>We require <code>code font</code> styling (monospace, sans-serif) for all text that refers
|
||
to a command or other input or output from the CLI. This includes file paths
|
||
(e.g., <code>/etc/hosts/docker.conf</code>). If you enclose text in backticks (`) markdown
|
||
will style the text as code. </p>
|
||
<p>Text from a CLI should be quoted verbatim, even if it contains errors or its
|
||
style contradicts this guide. You can add "(sic)" after the quote to indicate
|
||
the errors are in the quote and are not errors in our docs.</p>
|
||
<p>Text taken from a GUI (e.g., menu text or button text) should appear in "double
|
||
quotes". The text should take the exact same capitalisation, etc. as appears in
|
||
the GUI. E.g., Click "Continue" to save the settings.</p>
|
||
<p>Text that refers to a keyboard command or hotkey is capitalized (e.g., Ctrl-D).</p>
|
||
<p>When writing CLI examples, give the user hints by making the examples resemble
|
||
exactly what they see in their shell: </p>
|
||
<ul>
|
||
<li>Indent shell examples by 4 spaces so they get rendered as code blocks.</li>
|
||
<li>Start typed commands with <code>$</code> (dollar space), so that they are easily
|
||
differentiated from program output.</li>
|
||
<li>Program output has no prefix.</li>
|
||
<li>Comments begin with # (hash space).</li>
|
||
<li>In-container shell commands, begin with <code>$$</code> (dollar dollar space).</li>
|
||
</ul>
|
||
<p>Please test all code samples to ensure that they are correct and functional so
|
||
that users can successfully cut-and-paste samples directly into the CLI.</p>
|
||
<h2 id="pull-requests">Pull requests</h2>
|
||
<p>The pull request (PR) process is in place so that we can ensure changes made to
|
||
the docs are the best changes possible. A good PR will do some or all of the
|
||
following:</p>
|
||
<ul>
|
||
<li>Explain why the change is needed</li>
|
||
<li>Point out potential issues or questions</li>
|
||
<li>Ask for help from experts in the company or the community</li>
|
||
<li>Encourage feedback from core developers and others involved in creating the
|
||
software being documented.</li>
|
||
</ul>
|
||
<p>Writing a PR that is singular in focus and has clear objectives will encourage
|
||
all of the above. Done correctly, the process allows reviewers (maintainers and
|
||
community members) to validate the claims of the documentation and identify
|
||
potential problems in communication or presentation. </p>
|
||
<h3 id="commit-messages">Commit messages</h3>
|
||
<p>In order to write clear, useful commit messages, please follow these
|
||
<a href="http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message">recommendations</a>.</p>
|
||
<h2 id="links">Links</h2>
|
||
<p>For accessibility and usability reasons, avoid using phrases such as "click
|
||
here" for link text. Recast your sentence so that the link text describes the
|
||
content of the link, as we did in the
|
||
<a href="#commit-messages">"Commit messages" section</a> above.</p>
|
||
<p>You can use relative links (../linkeditem) to link to other pages in Docker's
|
||
documentation.</p>
|
||
<h2 id="graphics">Graphics</h2>
|
||
<p>When you need to add a graphic, try to make the file-size as small as possible.
|
||
If you need help reducing file-size of a high-resolution image, feel free to
|
||
contact us for help.
|
||
Usually, graphics should go in the same directory as the .md file that
|
||
references them, or in a subdirectory for images if one already exists.</p>
|
||
<p>The preferred file format for graphics is PNG, but GIF and JPG are also
|
||
acceptable. </p>
|
||
<p>If you are referring to a specific part of the UI in an image, use
|
||
call-outs (circles and arrows or lines) to highlight what you’re referring to.
|
||
Line width for call-outs should not exceed five pixels. The preferred color for
|
||
call-outs is red.</p>
|
||
<p>Be sure to include descriptive alt-text for the graphic. This greatly helps
|
||
users with accessibility issues.</p>
|
||
<p>Lastly, be sure you have permission to use any included graphics.</p>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="push-footer"></div>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
<div id="footer-container" class="container">
|
||
<div id="footer" class="grey-body">
|
||
<div class="row">
|
||
<div class="span2">
|
||
<span class="footer-title">Community</span>
|
||
<ul class="unstyled">
|
||
<li><a class="primary-button" href="https://www.docker.com/community/events/">Events</a></li>
|
||
<li><a class="primary-button" href="http://posts.docker.com">Friends' Posts</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/community/meetups/">Meetups</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/community/governance/">Governance</a></li>
|
||
<li><a class="primary-button" href="http://forums.docker.com">Forums</a></li>
|
||
<li><a class="primary-button" href="http://botbot.me/freenode/docker">IRC</a></li>
|
||
<li><a class="primary-button" href="https://github.com/docker/docker">GitHub</a></li>
|
||
<li><a class="primary-button" href="http://stackoverflow.com/search?q=docker">Stackoverflow</a></li>
|
||
<li><a class="primary-button" href="http://www.cafepress.com/docker">Swag</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="span2">
|
||
<span class="footer-title">Enterprise</span>
|
||
<ul class="unstyled">
|
||
<li><a class="primary-button" href="https://www.docker.com/enterprise/support/">Support</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/enterprise/education/">Education</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/enterprise/services/">Services</a></li>
|
||
</ul>
|
||
<span class="footer-title">Partner Solutions</span>
|
||
<ul class="unstyled">
|
||
<li><a class="primary-button" href="https://www.docker.com/partners/find/">Find a Partner</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/partners/program/">Partner Program</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/partners/learn/">Learn More</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="span2">
|
||
<span class="footer-title">Resources</span>
|
||
<ul class="unstyled">
|
||
<li><a class="primary-button" href="https://docs.docker.com">Documentation</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/resources/help/">Help</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/resources/usecases/">Use Cases</a></li>
|
||
<li><a class="primary-button" href="http://www.docker.com/tryit/">Online Tutorial</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/resources/howtobuy/">How To Buy</a></li>
|
||
<li><a class="primary-button" href="http://status.docker.com">Status</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/resources/security/">Security</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="span2">
|
||
<span class="footer-title">Company</span>
|
||
<ul class="unstyled">
|
||
<li><a class="primary-button" href="https://www.docker.com/company/aboutus/">About Us</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/company/team/">Team</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/company/news/">News</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/company/press/">Press</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/company/careers/">Careers</a></li>
|
||
<li><a class="primary-button" href="https://www.docker.com/company/contact/">Contact</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="span3">
|
||
<span class="footer-title">Connect</span>
|
||
<div class="search">
|
||
<span>Subscribe to our newsletter</span>
|
||
<form action="https://www.docker.com/subscribe_newsletter/" method="post">
|
||
<input type='hidden' name='csrfmiddlewaretoken' value='aWL78QXQkY8DSKNYh6cl08p5eTLl7sOa' />
|
||
<tr><th><label for="id_email">Email:</label></th><td><input class="form-control" id="id_email" name="email" placeholder="Enter your email" type="text" /></td></tr>
|
||
|
||
<button type="submit"><i class="icon-arrow-right"></i> </button>
|
||
</form>
|
||
</div>
|
||
<ul class="unstyled social">
|
||
<li><a title="Docker on Twitter" class="primary-button blog" href="http://blog.docker.com">Blog</a></li>
|
||
<li><a title="Docker on Twitter" class="primary-button twitter" href="http://twitter.com/docker">Twitter</a></li>
|
||
<li><a title="Docker on Google+" class="primary-button googleplus" href="https://plus.google.com/u/0/communities/108146856671494713993">Google+</a></li>
|
||
<li><a title="Docker on Facebook" class="primary-button facebook" href="https://www.facebook.com/docker.run">Facebook</a></li>
|
||
<li><a title="Docker on Youtube" class="primary-button youtube" href="http://www.youtube.com/user/dockerrun">YouTube</a></li>
|
||
</ul>
|
||
<ul class="unstyled social">
|
||
<li><a title="Docker on SlideShare" class="primary-button slideshare" href="http://www.slideshare.net/Docker">Slideshare</a></li>
|
||
<li>
|
||
<a title="Docker on LinkedIn" class="primary-button" href="https://www.linkedin.com/company/docker">
|
||
<span class="linkedin"></span>
|
||
LinkedIn
|
||
</a>
|
||
</li>
|
||
<li>
|
||
<a title="Docker on GitHub" class="primary-button" href="https://github.com/docker/">
|
||
<span class="github"></span>
|
||
GitHub
|
||
</a>
|
||
</li>
|
||
<li>
|
||
<a title="Docker on Reddit" class="primary-button" href="http://www.reddit.com/r/docker">
|
||
<span class="reddit"></span>
|
||
Reddit
|
||
</a>
|
||
</li>
|
||
<li>
|
||
<a title="Docker on AngelList" class="primary-button" href="https://angel.co/docker-inc-1">
|
||
<span class="angellist"></span>
|
||
AngelList
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div class="row clearfix">
|
||
<div class="span6 pagination-right copyright">
|
||
<span>© 2014-2015 Docker, Inc.</span>
|
||
</div>
|
||
<div class="span6 pagination-left copyright">
|
||
<a href="http://www.docker.com/legal/terms_of_service">Terms</a> ·
|
||
<a href="http://www.docker.com/legal/privacy_policy">Privacy</a> ·
|
||
<a href="http://www.docker.com/legal/trademark_guidelines">Trademarks</a>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<script src="/js/jquery-1.10.2.min.js"></script>
|
||
<script src="/js/jquery.cookie.js" ></script>
|
||
<script src="/js/jquery-scrolltofixed-min.js"></script>
|
||
<script src="/js/bootstrap-3.0.3.min.js"></script>
|
||
<script src="/js/prettify-1.0.min.js"></script>
|
||
<script src="/js/dockerfile_tutorial.js"></script>
|
||
<script src="/js/dockerfile_tutorial_level.js"></script>
|
||
<script src="/js/base.js"></script>
|
||
<script src="/tipuesearch/tipuesearch_set.js"></script>
|
||
<script src="/tipuesearch/tipuesearch.min.js"></script>
|
||
<script type="text/javascript">
|
||
piAId = '45082';
|
||
piCId = '1482';
|
||
|
||
(function() {
|
||
function async_load(){
|
||
var s = document.createElement('script'); s.type = 'text/javascript';
|
||
s.src = ('https:' == document.location.protocol ? 'https://pi' : 'http://cdn') + '.pardot.com/pd.js';
|
||
var c = document.getElementsByTagName('script')[0]; c.parentNode.insertBefore(s, c);
|
||
}
|
||
if(window.attachEvent) { window.attachEvent('onload', async_load); }
|
||
else { window.addEventListener('load', async_load, false); }
|
||
})();
|
||
</script>
|
||
<script type="text/javascript">
|
||
$(document).ready(function() {
|
||
$('#content').css("min-height", $(window).height() - 553 );
|
||
// if the URL contains a version string, update the version picker to reflect that
|
||
version = document.location.pathname.match(/^\/(v\d\.\d)\/.*/)
|
||
if (version && version[1]) {
|
||
$('#document-version-number')[0].text = 'Version '+version[1];
|
||
} else {
|
||
$('#document-version-number')[0].text = $('#document-version-number')[0].text + " (Latest)"
|
||
}
|
||
// load the complete versions list
|
||
$.get("/versions.html_fragment", function( data ) {
|
||
$('#documentation-version-list').prepend(data);
|
||
//remove any "/v1.1/" bits from front, so we can add the path to the version selection dropdown.
|
||
path = document.location.pathname.replace(/^\/v\d\.\d/, "");
|
||
$('#documentation-version-list a.version').each(function(i, e) {
|
||
e.href = e.href+path;
|
||
$(e).removeClass()
|
||
});
|
||
});
|
||
|
||
})
|
||
var userName = getCookie('docker_sso_username');
|
||
if (userName) {
|
||
$('.topmostnav_loggedout').hide();
|
||
$('.topmostnav_loggedin').show();
|
||
$('#logged-in-header-username').text(userName);
|
||
} else {
|
||
$('.topmostnav_loggedout').show();
|
||
$('.topmostnav_loggedin').hide();
|
||
}
|
||
</script>
|
||
</body>
|
||
</html> |