New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

First pass at copy guidelines #7588

Merged
merged 1 commit into from Jul 1, 2018

Conversation

Projects
None yet
5 participants
@karmatosed
Member

karmatosed commented Jun 27, 2018

@karmatosed karmatosed referenced this pull request Jun 27, 2018

Merged

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

4 of 4 tasks complete
@michelleweber

This comment has been minimized.

michelleweber commented Jun 27, 2018

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?

> 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 comment has been minimized.

@tofumatt

tofumatt Jun 27, 2018

Member

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.)

This comment has been minimized.

@karmatosed

karmatosed Jun 28, 2018

Member

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

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

This comment has been minimized.

@tofumatt

tofumatt Jun 27, 2018

Member

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?

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.)

This comment has been minimized.

@tofumatt

tofumatt Jun 27, 2018

Member

"They're" > "Contractions are".

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.”

This comment has been minimized.

@tofumatt

tofumatt Jun 27, 2018

Member

The commas should go outside the quotes.

This comment has been minimized.

@michelleweber

michelleweber Jun 27, 2018

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.

This comment has been minimized.

@tofumatt

tofumatt Jun 27, 2018

Member

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 😉

🤷‍♂️

This comment has been minimized.

@ZebulanStanphill

ZebulanStanphill Jun 27, 2018

Contributor

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?

This comment has been minimized.

@michelleweber

michelleweber Jun 28, 2018

Italics seem like a great solution :)

> 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 comment has been minimized.

@tofumatt

tofumatt Jun 27, 2018

Member

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.

> 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.

This comment has been minimized.

@tofumatt

tofumatt Jun 27, 2018

Member

" -- " should be "–"

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 comment has been minimized.

@tofumatt

tofumatt Jun 27, 2018

Member

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

This comment has been minimized.

michelleweber commented Jun 27, 2018

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

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).

This comment has been minimized.

@noisysocks

noisysocks Jun 28, 2018

Member

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.

screen shot 2018-06-28 at 10 06 37

screen shot 2018-06-28 at 10 08 16

screen shot 2018-06-28 at 10 06 46

screen shot 2018-06-28 at 10 06 53

This comment has been minimized.

@michelleweber

michelleweber Jun 28, 2018

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

  1. Title case
  2. 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

This comment has been minimized.

Member

karmatosed commented Jun 28, 2018

@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

This comment has been minimized.

Member

tofumatt commented Jun 28, 2018

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

This comment has been minimized.

Member

karmatosed commented Jun 28, 2018

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.

@karmatosed karmatosed merged commit 345e1ea into master Jul 1, 2018

2 checks passed

codecov/project 46.93% remains the same compared to fffd8e3
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment