Create a writing style guide

[jugglinmike]

If there are any expected writing-style-related conventions that the project would like to maintain, they should be documented and referenced in the project's readme.

This documentation is especially important considering that much of the content is currently sourced from a single author, making it difficult to infer what aspects of the style are intentional.

Note that some of the currently-accepted articles may need to be updated in order to comply.

Some conventions include:

• Point of view
  • First-person? (relating personal experiences)
  • Second person? (addressing the reader directly)
• Use of contractions
• Use of humor
• Citation
  • Acceptable external resources
  • Method (inline hyperlinks? reference numbers with links listed after the article?)

[addyosmani]

//cc @ajpiano @kswedberg

If we're following the approach taken by the jQuery docs team for their documentation, I would suggest:

• Point of view: one/we over you/your
• Contractions: should be fine to use. I haven't seen any mis-use of contractions so far
• Humor: Typically avoided. Whilst we're huuge on humor otherwise, docs should aim to be authoritative over funny. It's also difficult for humor to be consistently maintained with so many people involved in contributing to this project.
• Citation: Preference is on using up to date external resources if we're making citations. References should be inline over having reference numbers used and listed at the end of the article.

If Karl or Adam have further comments to add those would be great. We can then formalize this into the readme.

[ajpiano]

Agree WRT Contractions and citation

I'm not crazy about eliminating second-person, a lot of things would be made rather awkward (if a simple sub-in process were adopted) or extensively rephrased. First-person plural works nicely in tutorials, when "we're" doing something together, but when the author is specifically talking to the reader, having the second person available makes sense. Third-person singular tends to come off a bit distant.

I don't think we should have an explicit policy about "avoiding humor." I don't think we are going to be having a tonne of content that is going to be fertile ground for great jokes, but they should be examined on a case-by-case basis. These aren't API docs, they are "narrative" documentation and humor can be useful and I'd rather not dampen people's inclinations prematurely lest they assume we'll always prefer the dour to the sublime.

[addyosmani]

^ I'm cool with Adam's take on this with respect to humor and the point of view :) Deciding on a case by case basis does make sense.

[kswedberg]

You might want to take a look at the style guidelines at https://github.com/jquery/api.jquery.com#style-guidelines and use them as a springboard for the guidelines here.

[addyosmani]

Good point, @kswedberg. Thanks for the heads up. We can definitely build on that!

[kevee]

Something that is bugging me about headings is that there is no recommendation regarding using title case or "radical lower-case" (i.e. first word of headings is capitalized, the rest aren't).

[dmzza]

Use markdown italics for vocabulary terms instead of capitalizing.

Ex:

This is called event delegation and it's a great feature.

[RedWolves]

Need to adapt from api style guide to be specific to learn site.