Set a tone / style for the book

tooling / book-of-modern-frontend-tooling

The Front-end Tooling Book

http://tooling.github.io/book-of-modern-frontend-tooling/

2.53k stars 177 forks source link

Set a tone / style for the book #25

Open belen-albeza opened 10 years ago

belen-albeza commented 10 years ago

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 commented 10 years ago

@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 commented 10 years ago

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 commented 10 years ago

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

addyosmani commented 10 years ago

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.