📝 doc: begin content style guide with voice and tone#14
📝 doc: begin content style guide with voice and tone#14maddhruv merged 4 commits intonodejs:masterfrom
Conversation
|
I like the tone and voice of the document, but feel some of the examples don't really follow it. We say not to use: "The GitHub issues list is the place for discussion of Node.js core features." But the body it says (as an example): "To achieve this, consider addressing your reader like a friend." Which IMHO are really similar and direct in tone. I think a more direct approach, while still polite, might benefit everyone. From these three alternatives:
I think 2. and even 3. win hands down. In fact they are the most common ones I've seen and even this voice-and-tone-guideline follows style 2-3 and not 1. Too much fluff and the content gets lost, but I do agree that too dry and it feels like a series of orders or commands. Other things to consider: Voice: what person? Are we making the reader/future writer belong to Node.js by using a plural "we"? Or are we telling them how to behave by using "you"? Example:
This is normally overlooked and documentation writers often switched between "you" and "we" in very similar contexts (I am sure I've done it hundreds of times). I think both are fine and depend on the goal. Personally I prefer "we" and I think to match our objectives "we" would be strongly preferred. Also it allows for a more non-threatening tone. In this same comment I wrote:
If I had say:
It would feel a lot more personal, the subject of my critic would be you, while that is the last thing I want! What do you and everyone think of these two points? I can do a PR with these two modifications. |
| They might say: _"How do I load another .js file and run that new .js file in a new | ||
| global context?..."_ | ||
|
|
||
| You might respond: _"If you really want to do this, you will need to put a wrapper |
There was a problem hiding this comment.
imo if you really want to do this should not be said here, rather, it should be explained immediately why you shouldn't do this
|
|
||
| * **Do: Active voice** Use active voice. Avoid passive voice. | ||
| * **Don't: Jargon (and slang)** Write in vanilla English. | ||
| * **Do: Positivity** Use positive language, instead of negative language. |
There was a problem hiding this comment.
resources for using positive and negative language?
There was a problem hiding this comment.
Good point. This one cites sources and has dos vs don'ts. https://www.plainlanguage.gov/guidelines/concise/use-positive-language/
Putting in the next commit.
|
|
||
| The content we make available on [Node.js](https://nodejs.org/en/) is for many different people and teams. They will use it to make decisions about teaching themselves Node.js, using it for their projects, and about contributing to its development. | ||
|
|
||
| We can write content that empowers their decision by being aware of our voice and our tone. Now, let's get to it. What’s the difference between voice and tone? |
There was a problem hiding this comment.
I feel like the second sentence here is superfluous
| upset as you would with someone who’s happy. | ||
|
|
||
| Our voice doesn’t change much from day to day, but our tone changes all the time. | ||
|
|
There was a problem hiding this comment.
A short, one-sentence comparison of tone vs voice with a little allegory or something here would be cool!
There was a problem hiding this comment.
I'm blanking on this right now 🤦🏽♂️
|
|
||
| ## Our voice | ||
|
|
||
| Node.js’ voice is relatable. It’s friendly, encouraging, and clear. Our priority |
There was a problem hiding this comment.
maybe explain "relatable" here, it's a vague term
|
Thank you for a specific feedback @oe and @franciscop! 🙏🏽 I've pushed another commit with some updates. There are some suggestions where I would benefit from some clarification. Where applicable, I've replied directly to @oe's review comments, and to @franciscop, I'm doing so below.
I agree that this guide is more direct than inviting. To help us work through this, I've redone the parts that seem to most contradict its suggestions. Maybe seeing it will help to better find a balance between losing content vs being a series of orders! Please do feel free to comment directly on the parts that could use reworking.
My intent by using the pronoun "you" was to make the guide be more personal. But if the impression being made is that the voice is prescriptive, I would strongly support using "we". I do think "we" is more non-threatening and more inclusive. Thanks again @franciscop and @oe for taking the time to read through this and make suggestions! 💯 |
3 participants
This PR starts work on #13. This initial document owes much of its inspiration to the resources suggested in the original description there.
I believe the purpose of the issue is to standardize our content creation for this project. This initial Tone and Voice document could be split up better into more focused documents. But that may be beyond scope. If it's not beyond scope, I hope that this can evolve into something much like this Content Style Guide but for the open source projects that is Node.js 💛 If so, I have some ideas bouncing around.
Either way, I intend to continue working on this. And I would welcome any changes and comments to make this more useful for the target audience! 🙏