First pass at copy guidelines #7588

karmatosed · 2018-06-27T19:34:29Z

Props @michelleweber

@michelleweber

Props @michelleweber

michelleweber · 2018-06-27T20:01:33Z

Let me know what I can improve or clarify!

tofumatt

This is cool; I have some thoughts but realised I'm probably going to add too many little copyedits to be useful.

Is it cool if I made some copy edits and pushed to this branch?

tofumatt · 2018-06-27T22:07:41Z

docs/reference/copy-guide.md

+
+> This block can be used to display single images.
+
+Any time you see phrases like “can be” or “is used”: halt. You’re writing in the passive voice. Try going active for a snappier (and shorter) sentence:


Instead of "halt" (which admittedly did stop me reading the sentence), you could use a verb like "rephrase" or "reevaluate". That way you're telling them what to do and what to expect rather than just shutting them down (and getting the reader to pause without action for a moment, as I did.)

I think saying halt is ok as got you to do what it was intended.

tofumatt · 2018-06-27T22:09:17Z

docs/reference/copy-guide.md

+
+This will obviously vary quite a lot depending on the context, but here are some general tips:
+
+#### ONE: Contractions are your friends!


If these are to be numbered, can we use numbers? eg ### 1. Contractions. That said I'm not sure why you'd number them if the list doesn't appear elsewhere. I'd expect the list first (like a table of contents), then each point expanded on after.

Also shouldn't these be H3s not H4s?

tofumatt · 2018-06-27T22:09:48Z

docs/reference/copy-guide.md

+This will obviously vary quite a lot depending on the context, but here are some general tips:
+
+#### ONE: Contractions are your friends!
+They’re more conversational, and a simple way to make text sound friendlier and less formal. (And they save a bit of space as well: a win-win.)


"They're" > "Contractions are".

tofumatt · 2018-06-27T22:10:36Z

docs/reference/copy-guide.md

+
+The more direct sentences are almost always clearer. Scan your copy for the words “can,” “be,” “might,” “allows you to,” and “helps” -- they’re the most common culprits, and looking for those words specifically is a way to locate phrasing you can tighten up. 
+
+#### THREE: Beware of “simple,” “easy,” and “just.” 


The commas should go outside the quotes.

I'm not sure what WordPress.org punctuation standards are, but WordPress.com standards (which is where I come from) are U.S. punctuation, where they go inside the quotes.

Even in a list like that? Whoa… I mean whatever the style guide says… but that's extremely difficult for me to read.

I thought for quotes in prose (eg quoting someone) they went inside, but that looks like a list; I'd expect the commas after each item, not inside it.

I think this will confuse programmers 😉

🤷‍♂️

The rules are a bit uncertain when it comes to instances where quotation marks are used for object titles rather than actual quotes. Here is a Quora page I found after a quick search:

https://www.quora.com/When-writing-a-list-in-which-the-items-are-in-quotations-should-the-comma-go-inside-the-quotes-or-outside

I am fairly certain my English textbooks would always put commas after the quotation marks in a list of words. Off the top of my head, that seems to be the standard that I see used in most places, but I could be misremembering. Whatever the case, having commas within the quotation marks in this instance looks more confusing to me.

Perhaps the issue could be avoided entirely by simply italicizing the words and avoiding the usage of quotation marks?

Italics seem like a great solution :)

tofumatt · 2018-06-27T22:12:06Z

docs/reference/copy-guide.md

+
+> The gallery block can help you display multiple images in an elegant layout.
+
+Does it or doesn’t it? We’re making this software: we’re allowed to be declarative about what it is and does:


This sort of conversational format is neat and I like the comparisons but each before/after would benefit from more sectioning off (a header? even an <hr>); right now I find it hard to connect which section is dealing with which and if we've changed sentences.

tofumatt · 2018-06-27T22:12:52Z

docs/reference/copy-guide.md

+
+> Preformatted text preserves your tabs and line breaks.
+
+The more direct sentences are almost always clearer. Scan your copy for the words “can,” “be,” “might,” “allows you to,” and “helps” -- they’re the most common culprits, and looking for those words specifically is a way to locate phrasing you can tighten up. 


" -- " should be "–"

tofumatt · 2018-06-27T22:13:44Z

docs/reference/copy-guide.md

+We’re the only ones that care about what we did or want; the user just wants software that works. If you see a lot of “we”s, think about whether you should reframe what you’re writing to focus on the benefits to and successes of the user.
+
+## Bulleted Lists
+Guidelines for (duh) writing bulleted lists.


This "duh" here is jarring and might be weird to an ESL user. At any rate I don't think it's helpful (or funny) so should be removed.

michelleweber · 2018-06-27T22:36:01Z

This is for y'all, so you should adjust it however you see fit.

noisysocks · 2018-06-28T00:10:01Z

docs/reference/copy-guide.md

+
+In sentence case, only the first letter of the line is capitalized
+
+Feature names and dashboard sections typically use title case (think “Site Stats” or “Recently Published”), whereas feature labels typically use sentence case (like “Show buttons on” or “Comment Likes are,” where “Likes” is capitalized because it’s the feature name, but the overall label is using sentence case).


Could we clarify here whether or not we should use sentence case or title case for UI controls such as buttons? I'm often confused about which style to use when developing features. There's sometimes conflicting examples throughout the interface.

It's actually not even clear what case these are in! They could be:

Title case

Sentence case, but with capitalized the block names, so they effectively look like title case

We should first update to specific whether block names are/are not proper nouns (and therefore always capitalized), and then y'all should decide what case you prefer for these controls.

Fun with capitalization :)

karmatosed · 2018-06-28T09:30:50Z

@tofumatt I would prefer in this case we get things in and then have discussion to iterate. It's pretty solid from @michelleweber and I think that's good. Right not it's super crucial to have something. After we get in do you want to then start an issue with some suggestions?

tofumatt · 2018-06-28T09:36:00Z

I'll make a PR with suggestions as I have a lot then, it'll be more constructive for me to do that than add a lot of comments; GitHub is better for prose editing than it used to be but it's still a bit noisy.

karmatosed · 2018-06-28T09:49:35Z

Thanks @tofumatt could you give a review to commit just so we get this in then?

tofumatt

Ten-four; filed #7598 to work on improvements.

Create first pass at copy guidelines

56516e7

Props @michelleweber

karmatosed mentioned this pull request Jun 27, 2018

fix: Improve "add block" text in NUX onboarding #7511

Merged

4 tasks

tofumatt reviewed Jun 27, 2018

View reviewed changes

noisysocks reviewed Jun 28, 2018

View reviewed changes

tofumatt mentioned this pull request Jun 28, 2018

Make clarifications and tweaks to copy documentation #7598

Closed

tofumatt approved these changes Jun 28, 2018

View reviewed changes

karmatosed merged commit 345e1ea into master Jul 1, 2018

Soean mentioned this pull request Jul 9, 2018

Make strings consistent, lower vs. Upper case #6210

Closed

leahkoerper mentioned this pull request Aug 14, 2018

Copy guidelines formatting tweaks #8952

Merged

aduth deleted the karmatosed-patch-2 branch January 25, 2019 21:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

First pass at copy guidelines #7588

First pass at copy guidelines #7588

karmatosed commented Jun 27, 2018

michelleweber commented Jun 27, 2018

tofumatt left a comment

tofumatt Jun 27, 2018

karmatosed Jun 28, 2018

tofumatt Jun 27, 2018

tofumatt Jun 27, 2018

tofumatt Jun 27, 2018

michelleweber Jun 27, 2018

tofumatt Jun 27, 2018

ZebulanStanphill Jun 27, 2018 •

edited

Loading

michelleweber Jun 28, 2018

tofumatt Jun 27, 2018 •

edited

Loading

tofumatt Jun 27, 2018

tofumatt Jun 27, 2018

michelleweber commented Jun 27, 2018

noisysocks Jun 28, 2018

michelleweber Jun 28, 2018

karmatosed commented Jun 28, 2018

tofumatt commented Jun 28, 2018

karmatosed commented Jun 28, 2018

tofumatt left a comment


		> This block can be used to display single images.

		Any time you see phrases like “can be” or “is used”: halt. You’re writing in the passive voice. Try going active for a snappier (and shorter) sentence:


		This will obviously vary quite a lot depending on the context, but here are some general tips:

		#### ONE: Contractions are your friends!


		The more direct sentences are almost always clearer. Scan your copy for the words “can,” “be,” “might,” “allows you to,” and “helps” -- they’re the most common culprits, and looking for those words specifically is a way to locate phrasing you can tighten up.

		#### THREE: Beware of “simple,” “easy,” and “just.”


		> The gallery block can help you display multiple images in an elegant layout.

		Does it or doesn’t it? We’re making this software: we’re allowed to be declarative about what it is and does:


		> Preformatted text preserves your tabs and line breaks.

		The more direct sentences are almost always clearer. Scan your copy for the words “can,” “be,” “might,” “allows you to,” and “helps” -- they’re the most common culprits, and looking for those words specifically is a way to locate phrasing you can tighten up.


		In sentence case, only the first letter of the line is capitalized

		Feature names and dashboard sections typically use title case (think “Site Stats” or “Recently Published”), whereas feature labels typically use sentence case (like “Show buttons on” or “Comment Likes are,” where “Likes” is capitalized because it’s the feature name, but the overall label is using sentence case).

First pass at copy guidelines #7588

First pass at copy guidelines #7588

Conversation

karmatosed commented Jun 27, 2018

michelleweber commented Jun 27, 2018

tofumatt 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

ZebulanStanphill Jun 27, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tofumatt Jun 27, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michelleweber commented Jun 27, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

karmatosed commented Jun 28, 2018

tofumatt commented Jun 28, 2018

karmatosed commented Jun 28, 2018

tofumatt left a comment

Choose a reason for hiding this comment

ZebulanStanphill Jun 27, 2018 •

edited

Loading

tofumatt Jun 27, 2018 •

edited

Loading