Vue Docs Writing Guide #2317
Vue Docs Writing Guide #2317
Conversation
There was a problem hiding this comment.
Nice work @chrisvfritz! I've added a couple of comments inline. I also have several extra suggestions here:
- No use of emojis. Emojis are cute and friendly and all, but they don't belong to docs. Leave them for discussions 😊 (see what I did there?)
- Avoid using words like "easy," "just," "obviously" etc. We can provide a link to this article by Chris Coyier Words To Avoid in Educational Writing in the Resources section as well.
- (To be continued when/if I have more).
writing-guide.md
Outdated
| - **Don't litter the document with tips and caveats.** If you find that more than two tips are needed per page, consider adding a caveats section to address these issues. The guide is meant to be read straight through, and tips and caveats can be overwhelming or distracting to someone trying to understand the base concepts. | ||
| - **Avoid appeals to authority** (e.g. "you should do X, because that's a best practice" or "X is best because it gives you full separation of concerns"). Instead, demonstrate with examples the specific human problems caused and/or solved by a pattern. | ||
| - **When deciding what to teach first, think of what knowledge will provide the best power/effort ratio.** That means teaching whatever will help users solve the greatest pains or greatest number of problems, with the relatively least effort to learn. This helps learners feel smart, powerful, and curious, so their cognitive capacity will drain more slowly. | ||
| - **Unless the context assumes a string template or build system, only write code that works in any supported environment.** |
There was a problem hiding this comment.
What does "supported environment" mean in this case? (Or, can we elaborate that?)
There was a problem hiding this comment.
Just clarified. Let me know what you think!
| - **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").  | ||
| - **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". |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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 :)
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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. 🤷♂️
writing-guide.md
Outdated
| - **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". | ||
| - **Always prefer simpler, plainer language over complex or jargony language.** For example: | ||
| - "you can use Vue with a script element" instead of "in order to initiate the usage of Vue, one possible option is to actually inject it via a script HTML element" | ||
| - "function that returns a function" instead of "higher order function" |
There was a problem hiding this comment.
In this particular case, I'd argue that "higher-order function" is a well-known term that is expected to be used for the correct target audience. "Function that returns a function" is more verbose and at the same time insufficient.
There was a problem hiding this comment.
I'm open to changing this example, but here's my thinking. While "higher-order function" and even "higher-order component" may be well-known terms (i.e. many people - or at least those more experienced in the field or coming from a computer science background - have heard of them and even used them), I would argue they're not at all well-understood. If I did an offline poll in an advanced workshop/meetup/conference, I feel very confident that the majority of people would not be able to give a complete and accurate definition of either. It might even be impossible to give an "accurate" definition, since they seem to have different definitions depending on where you look. 😄
And their technical definitions often differ even further from how they're used by working developers. For example, I've never heard someone refer to a function that just accepts a callback a "higher-order function", but it fits the technical criteria. So do many constructors, if you count functions that return an object that has methods on it (or all constructors, if you count getters and setters). The most widely accepted technical definition of a "higher-order function" is possibly so vague as to be useless.
By avoiding jargon like this altogether and getting right to what we mean in a particular use case with "function that returns a function", we're clearer and more specific. At the cost of only two extra syllables, that seems like a deal! 😄
Do you disagree?
There was a problem hiding this comment.
If such a term is controversial, shouldn't we avoid it altogether and use another as an example?
There was a problem hiding this comment.
I don't think these terms are widely considered controversial - they're very commonly used and I see very few people questioning that use.
| - **While writing, don't be afraid to ask questions**, _especially_ if you're afraid they might be "dumb". Being vulnerable is hard, but it's the only way for us to more fully understand what we need to explain. | ||
| - **Be involved in feature discussions.** The best APIs come from documentation-driven development, where we build features that are easy to explain, rather than trying to figure out how to explain them later. Asking questions at this stage (again, especially the questions we're afraid are "dumb") often help reveal potential confusions, inconsistencies, and problematic behavior before it would require a breaking change to fix. | ||
|
|
||
| ## Organization |
There was a problem hiding this comment.
Can we somehow keep this section more concise? I personally find it a bit too wordy.
There was a problem hiding this comment.
I tried. 😅 You can let me know what you think. I'm open to specific suggestions.
There was a problem hiding this comment.
This looks ok to me, I know it's long, but that's also why we have the different bold and li, so people can scan
Co-Authored-By: Natalia Tepluhina <[email protected]>
There was a problem hiding this comment.
There are really only two things keeping us from merging at this point:
- lengthiness (if An is ok with us keeping it a bit long)
- official naming conventions of entities (I defer to An and Chris' judgement on this, but my take is written inline)
By me everything is good to merge, looking to Chris and An for resolution on the other two points.
| - **While writing, don't be afraid to ask questions**, _especially_ if you're afraid they might be "dumb". Being vulnerable is hard, but it's the only way for us to more fully understand what we need to explain. | ||
| - **Be involved in feature discussions.** The best APIs come from documentation-driven development, where we build features that are easy to explain, rather than trying to figure out how to explain them later. Asking questions at this stage (again, especially the questions we're afraid are "dumb") often help reveal potential confusions, inconsistencies, and problematic behavior before it would require a breaking change to fix. | ||
|
|
||
| ## Organization |
There was a problem hiding this comment.
This looks ok to me, I know it's long, but that's also why we have the different bold and li, so people can scan
| - **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").  | ||
| - **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". |
There was a problem hiding this comment.
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?
This is a writing guide that the docs team has worked together to develop, to help provide rules and recommendations to ourselves and contributors for writing and maintaining docs across the Vue ecosystem.