Set a tone / style for the book

[belen-albeza]

In order to provide something uniform (it's good for readers), we should decide which tone or style use. Stuff like:

• Informal? Formal? Can we have a sample text with the tone we would like, as reference?
• What style conventions for displaying tips, reserved words, etc?
• Which pronoun are we using to refer to third persons? (regardless of it being he/she/they we should decide one and be consistent).

Maybe the easiest way would be just have a text or book we like and adopt their style / conventions choices.

[addyosmani]

@belen-albeza thanks for bringing this up! I tried looking around for some style guides that would capture the above points and started working on https://github.com/tooling/authoring-styleguide. It's super-rough, but perhaps we could evolve it? Currently inspired by Rubenstein, O'Reilly authoring portal and MailChimp's style guide for their content.

[addyosmani]

If anyone has any comments or ideas for improving the style guide, I'd be happy to take them on-board. Otherwise we can continue iterating on it and suggest it as a guideline for those authoring chapters.

[tomByrer]

@addyosmani are you expecting alot of visuals for v1 please? How many-ish?

[addyosmani]

Imo, our guidance around the use of visuals should be liberal - i.e if an author feels that visuals aid the chapter, then by all means feel free to use them. One example might be demonstrating the output of a particular build step where you might be generating a bunch of files and it's beneficial to show the file tree of what was created.