English Writing Style Guide

[dm-murphy]

Title	Author	Date
English Writing Style Guide	Daniel Murphy	June 13 2022

English Writing Style Guide

Summary

As discussed with the Maintainer team, a note on the use of American style English was added as a general note to the Layout Style Guide (TheOdinProject/curriculum#24182).

Additionally we have discussed expanding a full English writing style guide for The Odin Project that would include writing style guidelines and examples on everything from word choice and punctuation to syntax and preferred stylings.

Motivation

A full writing style guide can help contributors know exactly what we mean by American English and American style punctuation. This will help alleviate issues where contributors use British English and punctuation that is inconsistent with the curriculum.

Additionally this gives us an opportunity to make suggestions on anything related to writing content for the curriculum and what our preferences are for language or format when talking about code.

Guidelines and examples within our own style guide would be more likely followed than linking contributors to an external resource.

Suggested Implementation

We would create a project with assignees to draft up an English writing style guide that is included in our repository and can be linked from the Layout Style Guide and/or the Odin Contributing Guide.

The guide would include explanations on American English, American style punctuation, preferred word choices, and formatting styles. These principles would include examples that show exactly what we prefer and make it easy for contributors to follow.

Drawbacks

As discussed among the maintainer team, this guide would take considerable time and effort in putting together. It would also require the maintainer team or the project team coming together on certain preferences to make sure we create a consistent style guide. There may be some upkeep after the initial guide is created but nothing as extreme as the initial effort to write it.

Alternatives

The alternative is to link contributors to an external resource instead of creating our own. A downsides to an external resource is that it may not include all of our preferences. Another downside is that it would require us figuring out what sort of external style guide we agree upon and is freely available to contributors.