Content Writing Guidelines

Audience

You might want to know about the app audience to help with your tone etc. Assume for now that it's:

• 50% non-technical young professionals who are curious about learning code, and/or how technical tools can help them
• 50% developers looking to sharpen or build new skills

Titles

All the titles in our content (Topic, Course, Workout, Insight, or Glossary) should be capitalized according to the Chicago Manual of Style.

For example, the title Fetching a remote branch should be Fetching a Remote Branch.

Content Types

You've probably already tried the app. Keep in mind that high-level product-wise we try to focus on the most valuable content for users while they're (obviously) on their phones. They're probably relaxing or on-the-go; and not by their desktop.

So we -try- to focus most on the benefits below within the app:

1. Awareness: overview of the "why"; highlighting important steps to get started, the most "wow" features, tips, tricks and gotchas
2. Curiosity: Give a teaser of something that can be done so they can dig into this later / separately
3. Mental Models: Things that can be communicated with a few sentences/examples -- but open up a broader or more fundamental understanding of a concept/feature.

We stay away from:

1. Things that need a lot of text. Instead, we rely on examples and images.
2. Things that require you to write code or use the product itself alongside to get value from the content.

For both of the above, we include links to "Learn More" which users can bookmark; they are then sent by email for them to try on their desktop.

The general theme is: what content can create a lot of value for that topic/area/concept relative to the time spent, likely while the user has a short attention span, and without having to build anything.

Writing Style: tips

• Focus on benefits and the why much more / sooner -- to get the user engaged
• Use spacing (new paragraph every 1-2 sentences mostly) -- so easier to read
• Focus on efficient phrasing, shorter sentences, and use apostrophes for omission (eg. can't instead of cannot) -- so easier to read
• Try to focus on questions & links to learn more which are genuinely useful. Not naive or "just to fill the space".
• Ensure grammar is accurate.
• Don't use slang, but be informal. Use words and phrasing as how you'd talk to a friendly colleague. Even experiment with playfulness where appropriate -- to make it more fun to read
• Remove or rephrase paragraphs that are unnecessarily repeated. The content should flow correctly if you read from top to bottom
• Avoid content - in particular, text-heavy - which is not essential or that app users will gloss over. Remove it or move elsewhere (eg. into the Learn More links to an external link).

Changelog

Whenever we make a change in our content we want to store the said change in our CHANGELOG.

This rule will only be enforced for internal contributors, but external contributors are encouraged to follow it as well.

The format is based on Keep a Changelog, and it was adapted for the curriculum repository:

## Date

### Type of change
- [Topic Name - Insight Name - Description of the change](link-to-the-PR-or-commit-where-the-change-was-added)

More details can be found at the top of the CHANGELOG file.