Converges titles to imperative-form, front-matter based, and sentence-case #438

johndmulhausen · 2016-11-02T22:52:29Z

Changes _layouts/docs.html to use {{ page.title }} from front-page matter, and makes the front-matter the authoritative source for page titles. Work done here:

Title casing converted to sentence casing
Gerunds in titles converted to imperative form
Disambiguation where page titles would be duplicated ("FAQ" for multiple products, etc) or otherwise vague in global contexts
title: replaced with text from first # H1 Title in cases of divergence
Some 80-column text wrapping (using Atom's CMD+ALT+Q command) when long lines were egregious enough to bug me

joaofnfernandes · 2016-11-03T00:14:47Z

docsarchive.md

@@ -2,8 +2,6 @@
 title: Documentation Archive


Should be "Documentation archive"?

joaofnfernandes · 2016-11-03T00:15:54Z

engine/admin/ansible.md

@@ -2,11 +2,9 @@
 description: Installation and using Docker via Ansible
 keywords:
 - ansible, installation, usage, docker,  documentation
-title: Using Ansible
+title: Use ansible


Ansible is a product, so it should be capitalized (at least according to their site)

joaofnfernandes

Other than the tiny nitpicks, LGTM

sanscontext · 2016-11-03T05:41:49Z

docker-cloud/builds/image-scan.md

-    weight: -55
-title: Docker Security Scanning
+- Docker, docker, scan, scanning, security, registry, plans, Docker Cloud, docs, documentation, trusted, builds, trusted builds, automated builds
+title: Docker security scanning


Security Scanning is a product name and should remain capitalized.

sanscontext · 2016-11-03T05:45:53Z

docker-cloud/builds/index.md

 notoc: true
-title: Builds and Images Overview
+title: Build and images overview


This should remain plural because you can have multiple builds. Also, as a landing/index page, it feels weird to decap Overview for some reason. 🤔

I really like sentence capitalization so "overview" doesn't look strange to me.
But you can always change the sentence to "Overview of build and images"

Yeah, I'll probably do that for all of the landing pages.

Done (pluralization) :)

sanscontext · 2016-11-03T05:46:33Z

docker-cloud/builds/link-source.md

-    parent: builds
-    weight: -60
-title: Link to a source code repository
+title: Link Docker Cloud to a source code provider


This is the long form, right? The shorter version appears nested in context in the left nav menu?

Exactly; in-page = longform, toc.yaml = shortform

sanscontext · 2016-11-03T05:47:55Z

docker-cloud/docker-errors-faq.md

-    parent: docker-cloud
-    weight: 50
-title: Known Issues in Docker Cloud
+title: Known Docker Engine issues in Docker Cloud


These are not all Engine specific errors (often it's just a collision), so it doesn't make sense to have "Docker Engine" in the title.

sanscontext · 2016-11-03T05:49:27Z

docker-cloud/dockerid.md

-    parent: docker-cloud
-    weight: -99
-title: Docker ID and Settings
+title: Your Docker ID and Docker Cloud account


Your Docker ID is your Docker Cloud account, so this isn't quite right. "Docker ID and Cloud Settings" is more correct.
(Again) this isn't reflected in the left nav, right?

Correct, it's not in the left-nav. Changed "account" to "settings"

sanscontext · 2016-11-03T05:55:04Z

docker-cloud/infrastructure/link-packet.md

-  main:
-    parent: infrastructure
-title: Link to Packet hosts
+title: Link your Packet account


s/your/to a
(same as ^ )

sanscontext · 2016-11-03T05:55:23Z

docker-cloud/infrastructure/link-softlayer.md

-  main:
-    parent: infrastructure
-title: Link to SoftLayer hosts
+title: Link your SoftLayer account


s/your/to a
(you probably get the picture by now ;) )

sanscontext · 2016-11-03T05:56:46Z

docker-cloud/slack-integration.md

-  main:
-    parent: docker-cloud
-title: Docker Cloud notifications in Slack
+title: Receive Docker Cloud notifications in Slack


This is probably more like "configure" or "set up", since receiving is sort of a passive thing that only happens once you've done that bit...

Done (went with "Set up")

sanscontext · 2016-11-03T05:59:03Z

docker-hub/orgs.md

-    parent: mn_pubhub
-    weight: -80
-title: Teams & Organizations
+title: Organizations and teams


Since we're specifying "in Docker Cloud" we might as well be specific on this one too and add "Docker Hub".

sanscontext · 2016-11-03T06:00:42Z

docker-hub/accounts.md

-  main:
-    parent: mn_pubhub
-    weight: -90
+- Docker, docker, trusted, sign-up, registry, accounts, plans, Dockerfile, Docker Hub, docs,  documentation
 title: Your Docker ID


"Docker ID and Docker Hub account"
(Same comment as in several others - I know the original title isn't great, so let's improve it.)

sanscontext · 2016-11-03T06:02:56Z

Some nits on titles. Should be quick changes, sorry for the large number of them.

joaofnfernandes · 2016-11-03T17:32:56Z

I don't see any changes to _data/toc.yaml file. Probably you also need to check it to be consistent in terms of capitalization.

johndmulhausen · 2016-11-03T18:00:34Z

@sanscontext - No worries on the # of comments, thanks so much for taking a look. :)
@joaofnfernandes Re: toc.yaml -- Yep, I'm thinking I want to be sure everyone signs off on the titles before I duplicate the changes over there.

Thanks for the feedback guys, digging into it now.

mdlinville

I pushed commits to change non-controversial titles for Engine. Had a few comments / questions along the way.

mdlinville · 2016-11-02T22:59:13Z

_layouts/docs.html

@@ -185,6 +185,7 @@
            </div>
            <div {% if page.notoc %} class="col-xs-12 col-sm-9 col-md-10" {% else %} class="col-xs-12 col-sm-9 col-md-8 col-xl-9" {% endif %} >
              <section class="section" id="DocumentationText">
+								<h1>{{ page.title }}</h1>


Can we do any kind of smart fall-back for if there is no title: in the frontmatter? Can we default to using the first header encountered in the file?

Wrapped in an "if" so that this only happens if there is a title. Which should be always, but yes, that will make it so we default to first header (which happens just through natural content rendering)

mdlinville · 2016-11-04T00:41:15Z

engine/admin/ambassador_pattern_linking.md

-  main:
-    parent: engine_admin
-    weight: 15
+- Examples, Usage, links, docker, documentation, examples, names, name,  container naming
 title: Link via an ambassador container


Oh, do I ever hate "via"? And what are we linking? This is OK for now I guess but we need to revisit this topic.

Agreed on anti-"via". (i18n PTSD)

Ack; sucky page title, I can't even discern what use case it's trying to document, honestly, and it uses Sven's personal Docker repo

mdlinville · 2016-11-04T16:42:37Z

engine/installation/cloud/index.md

-    weight: "-60"
-title: On cloud providers
+- Docker install
+title: Install Engine in the cloud


"in a public cloud" maybe? Or are you going for the "in the cloud" hype on purpose?

Switched to "on cloud hosts" which I see in other topics in this branch of the TOC

mdlinville · 2016-11-04T16:43:23Z

engine/installation/cloud/overview.md

-menu:
-  main:
-    parent: install_cloud
-    weight: -3
 title: Choose how to install


I hate this title. Maybe "Docker installation choices"? or "Choose your installation method"?

"Choose an installation method" (eschewing "your" for consistency, see upthread) sounds good - let's go with that

mdlinville · 2016-11-04T16:46:13Z

engine/reference/api/docker_io_accounts_api.md

-menu:
-  main:
-    parent: engine_remoteapi
-    weight: 90
 title: docker.io accounts API


Should this be 'docker.io Accounts API'? Not sure what the proper noun is, and it's awkward to start with a lowercase word.

Oh hey, this looks like Docker ID stuff, too.

Switched to: Accounts API for docker.io

mdlinville · 2016-11-04T16:47:19Z

engine/reference/api/hub_registry_spec.md

-  main:
-    parent: smn_hub_ref
-title: The Docker Hub and the Registry v1
+title: Docker Hub and Registry V1


I think maybe it should still be 'v1' with a lowercase 'v'

- Close docker#194 and fix - Fix and close docker#425 - Fix and close docker#417 - Fix and close docker#420 - Fix and close docker#422 - Adding in documentation build scripts - Fix and close docker#431 - Fix and close docker#438, and Fix and close docker#429 - Work on 441 - Adding in commands reference - Updating all the options to tables - Updating per Vivek docker#498 - Adding vivek's last suggestions Signed-off-by: Mary Anthony <mary@docker.com>

johndmulhausen added 2 commits November 2, 2016 15:29

Merging upstream changes

b5d493c

Display titles, fix Jekyll error

f18fcfa

joaofnfernandes reviewed Nov 3, 2016

View reviewed changes

joaofnfernandes approved these changes Nov 3, 2016

View reviewed changes

sanscontext reviewed Nov 3, 2016

View reviewed changes

johndmulhausen mentioned this pull request Nov 3, 2016

fix frontmatter keywords values in compose/reference/ files #448

Merged

Misty Stanley-Jones added 5 commits November 3, 2016 17:41

Update ansible.md

6f676ef

Update b2d_volume_resize.md

b1df3d1

Update last_page.md

8e4b36c

Update using_supervisord.md

f0520d4

Update index.md

f0c02bd

mdlinville suggested changes Nov 4, 2016

View reviewed changes

mdlinville mentioned this pull request Nov 4, 2016

Add installation instructions for rapsbian-jessie #445

Merged

Feedback responses

8c31b7b

mdlinville approved these changes Nov 4, 2016

View reviewed changes

johndmulhausen merged commit 558314b into master Nov 4, 2016

johndmulhausen deleted the metadatascrub branch November 8, 2016 00:33

Converges titles to imperative-form, front-matter based, and sentence-case #438

Converges titles to imperative-form, front-matter based, and sentence-case #438

Conversation

johndmulhausen commented Nov 2, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joaofnfernandes Nov 3, 2016 • edited Loading

Choose a reason for hiding this comment

joaofnfernandes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sanscontext commented Nov 3, 2016

joaofnfernandes commented Nov 3, 2016

johndmulhausen commented Nov 3, 2016 • edited Loading

mdlinville left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joaofnfernandes Nov 3, 2016 •

edited

Loading

johndmulhausen commented Nov 3, 2016 •

edited

Loading