Skip to content

Vue Docs Writing Guide #2317

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.

Sign up for GitHub

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

Merged
merged 12 commits into from
Oct 24, 2019
Merged

Vue Docs Writing Guide #2317

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
0cb573b
add vue docs writing guide
chrisvfritz Sep 27, 2019
f0cba12
add note about emoji to writing guide
chrisvfritz Sep 30, 2019
93952ed
add note about invalidating language to writing guide
chrisvfritz Sep 30, 2019
50409b6
add note about blending tips into content in writing guide
chrisvfritz Sep 30, 2019
acaeb33
capitalize Oxford in writing guide
chrisvfritz Sep 30, 2019
8d860aa
reword feature discussions note in writing guide
chrisvfritz Sep 30, 2019
d23b6c4
clarify 'supported environment' in writing guide
chrisvfritz Sep 30, 2019
d9bdaaf
add software resources to writing guide
chrisvfritz Sep 30, 2019
3bf20dc
clarify language in writing guide
chrisvfritz Sep 30, 2019
b4827c8
clarify language in writing guide
chrisvfritz Sep 30, 2019
62ccb2d
pull oxford comma image into repo
chrisvfritz Sep 30, 2019
94db5b7
add note about allowing abbreviation symbols on keyboards
chrisvfritz Oct 1, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
pull oxford comma image into repo
  • Loading branch information
@chrisvfritz
chrisvfritz committed Sep 30, 2019
commit 62ccb2d844cc4eb6045fbbae7c4ff27065cc5129
Binary file added src/images/oxford-comma.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion writing-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Writing documentation is an exercise in empathy. We're not describing an objecti

- **Avoid abbreviations** in writing and code examples (e.g. `attribute` is better than `attr`, `message` is better than `msg`), unless you are specifically referencing an abbreviation in an API (e.g. `$attrs`).
- **When referencing a directly following example, use a colon (`:`) to end a sentence**, rather than a period (`.`).
- **Use the Oxford comma** (e.g. "a, b, and c" instead of "a, b and c"). ![Why the Oxford comma is important](https://www.inkonhand.com/wp-content/uploads/2015/10/serialimage.jpg)
- **Use the Oxford comma** (e.g. "a, b, and c" instead of "a, b and c"). ![Why the Oxford comma is important](https://raw.githubusercontent.com/vuejs/vuejs.org/master/src/images/oxford-comma.jpg)
- **When referencing the name of a project, prioritize the broader conventions of English over internal branding conventions of that project.** For example, "webpack" and "npm" both disregard conventions such as "always start a word at the beginning of a sentence with a capital letter", "project names always use Title Case", and "acronyms are always capitalized". Instead, always write "Webpack and NPM" to provide a more consistent experience in the docs and avoid sentences like "If you don't want to use Vue CLI, you can use webpack or Rollup directly by installing them via npm or Yarn".
Copy link
Member

@phanan phanan Sep 27, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about this. Instead, I personally always respect the official name, for example, notice how it's always "npm" regardless of its position on the Wikipedia entry.

Copy link
Contributor Author

@chrisvfritz chrisvfritz Sep 30, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is definitely one of the more controversial conventions. 😄 Opinions also seem to differ wildly across cultures. But generally among the English-speaking population of the world, my informal observation has been that this really helps people who have not yet developed into experts in these ecosystems, because the branding conventions actually look like typos and disrupt their flow while reading.

The people I see complain about not respecting branding conventions are almost always ecosystem experts (and often technical writers themselves). While this group tends to be especially vocal, they're a minority and will also have the lowest baseline cognitive burden when reading, so they don't need as much help.

Does that make sense?

Copy link
Member

@phanan phanan Sep 30, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

because the branding conventions actually look like typos and disrupt their flow while reading.

I honestly don't think this is a convincing enough reason to not respect a name/branding. If I have a product named "foo," I would appreciate if it's written "foo" everywhere. At least that's what my years working in an agency taught me :)

Copy link
Contributor Author

@chrisvfritz chrisvfritz Sep 30, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I have a product named "foo," I would appreciate if it's written "foo" everywhere.

And I'd appreciate if "foo" didn't choose a naming convention that violated larger grammar conventions, but I won't try to force them to change it on their site, so I feel like I'm being more reasonable. 😄 That doesn't really tell me why their preference for lower-case is more important than the experience of our readers. I feel like respecting their branding conventions would be placing the desires of the powerful few (these big projects) over the needs of the vulnerable many (our readers, especially those who are already dealing with a significant cognitive burden from being new to the ecosystem/programming or not being fluent in English).

Can you explain your preference in more detail? Do you feel we're doing actual harm to these projects or our readers?

Copy link
Member

@phanan phanan Sep 30, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That doesn't really tell me why their preference for lower-case is more important than the experience of our readers.

This is one of the rare cases when I would put the "experience" of our readers (which, I'd argue, shouldn't be affected that much) lower. To me, a name/branding is extremely important, and not for us to alter/modify at will.

Copy link
Member

@phanan phanan Sep 30, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I should have added that tt's also more consistent (there's only one source of truth) and less thinking for contributors to just use the name as given by the people who named it.

Copy link
Contributor Author

@chrisvfritz chrisvfritz Oct 1, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I should have added that it's also more consistent

It sounds like we both value consistency - I just value consistency within a site/page/sentence for all projects rather than consistency with an individual project's site. In my case, the goal is to improve the experience of our readers, which you seem to agree is affected by this. In your case, what is the ultimate goal of the consistency you're striving for? What problem would we solve by following the branding conventions of an individual project over more global conventions?

less thinking for contributors to just use the name as given by the people who named it

I haven't seen this to be the case in practice, as many (probably most) people don't know the branding conventions of every project. I think it's easier to remember one rule (the rule for our docs) rather than many rules - one for each project we mention. Either way though, if someone gets it wrong, it's something that's easy for us to update ourselves pre-merge.

Copy link
Member

@sdras sdras Oct 3, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think in previous PRs we have been doing what @phanan suggests- of honoring the way that the company/entity themselves call themselves. What I've seen is that otherwise they do come and PR to correct it. Some have trademarks etc where they require a particular spelling or casing. Would you be open to changing it, Chris?

Copy link
Contributor Author

@chrisvfritz chrisvfritz Oct 4, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I don't mind if that's what the majority of the docs team prefers, though I think I'm still missing what the advantage would be. Even for entities with trademarks, like "npm", using the trademark as a noun rather than an adjective is already a violation (and one with greater risk of doing actual harm from my understanding, as that's what brought trademarks such as Kleenex and Xerox under threat). And I of course agree to updating in the case that we receive a cease and desist, but I still haven't heard any advantage to complying with mere requests. 🤷‍♂️

- **Use Title Case for headings** - at least for now, since it's what we use through the rest of the docs. There's research suggesting that sentence case (only first word of the heading starts with a capital) is actually superior for legibility and also reduces the cognitive overhead for documentation writers, since they don't have to try to remember whether to capitalize words like "and", "with", and "about".
- **Don't use emojis (except in discussions).** Emojis are cute and friendly, but they can be a distraction in documentation and some emoji even convey different meanings in different cultures.
Expand Down