Nodejs.dev: Voice and Tone Guidelines

[amiller-gh]

The new website should include Voice and Tone guidelines that will help standardize our approach to content writing moving forward.

Some prior work in the Node org can be found in the Evangelism Initiative Media Style Guide

Some great resources from around the web include:

• Mail Chimp V&T Guide
• 18F V&T Overview
• Salesforce Guidelines
• Buffer V&T

The Voice and Tone guide can (and should) be worked on now as we develop the site IA and wireframes – before we get to writing content!

[keywordnew]

@amiller-gh could you give #14 a look? I consider it a work-in-progress while I get a better feel of what this project needs :)

[keywordnew]

Pushed some new content to #14, re: humour in voice and the comparison of voice and tone.

Would welcome any sort of feedback.

[keywordnew]

Ping: @nodejs/i18n

Any feedback here would be helpful! 🙏🏽

Context:

• discussion
• humour section in draft voice and tone guidelines

Questions:

• Any guidelines around identifying when humour doesn’t translate?
• What is a reasonable fallback when this is the case?
• What would the translation team do when coming across such content?

[zeke]

Thanks for opening this, @amiller-gh. I didn't know there was a term for these concepts. Really interesting stuff.

[eojthebrave]

The Drupal community has done a fair amount of work on developing guidelines for writing the content of the Drupal 8 User Guide, which you can see here https://www.drupal.org/docs/user_guide_guidelines/guidelines.html. And a Content style guide that is supposed to be applied for content on Drupal.org which you can find here https://www.drupal.org/drupalorg/style-guide/content#voice that contains documentation about recommend voice and other suggestions.

Posting in-case either of those are useful to review while generating similar documents for the Node community.

[hmbeale]

This seems like a cool project and I'd like to help. I'm reading through the suggested V&T resources as well as the existing documentation and plan to submit a PR in the near future.

In the mean time, I would put forward The Elements of Style as a resource. It's a novella-length primer written by Strunk and White and it's probably the single most influential book on modern English style and usage. It can be found pretty easily in pdf format with a quick google search.

[keywordnew]

@eojthebrave Hi! Thanks for suggesting the Drupal content guidelines! Would you be willing to put some time into getting your suggestion implemented by making a PR?

Depending on the scope of what you had suggested, we could even shoot for a partial implementation, to get the ball rolling.

I'm happy to make myself available to help guide you through our process if you haven't been active in our project before! 💯

[keywordnew]

This seems like a cool project and I'd like to help.

@hmbeale Super cool to hear! 🎉

Related to the comment I made earlier, even a partial implementation would be a good way to get the ball rolling on making a first PR here. You are free to make multiple PRs after all.

Is there any particular section you'd like to focus on?

And as I also said earlier, I'm still happy to help guide you through our process if you haven't been active in our project before!

[hmbeale]

@chowdhurian

Above you posted

Any guidelines around identifying when humour doesn’t translate?
What is a reasonable fallback when this is the case?
What would the translation team do when coming across such content?

So I was thinking of helping out there. I'd also be interested in adjusting the opening sentences a bit to more strongly convey the importance of the redesigned site having a clear and coherent voice. I don't want to be disruptive though; just trying to figure out how to be most helpful.

I would appreciate any suggestions you have for submitting a good pull request, especially as I am somewhat new to working with GitHub, though I have already read https://github.com/nodejs/website-redesign/blob/master/CONTRIBUTING.md

Essentially I ought to submit a pull request to the below document, right?
https://github.com/nodejs/website-redesign/blob/master/style-guide/0001-voice-and-tone.md

[amiller-gh]

@hmbeale Yup, thats correct 🙂

You can fork this repository, pull it down, and start modifying the voice and tone markdown file. Once you have it in a place you like, you push it back up to your fork and Github will show you a button that says "open a pull request". That will create something like this where everyone can review the changes and, when ready, can be pulled in to the main repo.

Alternatively, I believe Github will let you click the "edit" button in the top right corner of https://github.com/nodejs/website-redesign/blob/master/style-guide/0001-voice-and-tone.md and do most of that forking / committing / open a PR work for you. You'll be able to edit the markdown file right in the browser. You can give that a shot too 👍

[add1sun]

@amiller-gh @chowdhurian I've been a bit out of the loop, focused on other things, but I wanted to put a note out there that we (Lullabot Education) have a copy editor on contract who is used to reviewing tech tutorials and web copy. Once we get the style guide sorted here and content being written, I'm game to pay for some of her time to provide consistent copy-editing and application of the style guide. Just give a shout when you think those services are needed and I'll hook it up.