Merge pull request #1121 from github/style-lists

Update docs for this project

Author: MikeMcQuaid

docs/content-model.md

@@ -5,37 +5,40 @@ This content was originally created and curated by GitHub, and covers topics tha
 
 For content that is specific to GitHub products, see:
 
-- help.github.com - gets existing users unstuck and back to work.
-- guides.github.com -  tutorials about a larger idea or product feature for new users.
+- [help.github.com](https://help.github.com) - gets existing users unstuck and back to work.
+- [guides.github.com](https://guides.github.com) -  tutorials about a larger idea or product feature for new users.
 
-Everything written in the guides should fall into one of the following categories.
+Everything written in the guides should fall into one of the following categories:
 
-## Concept Guides
+- **Concept guides** dive deep into a specific topic (for example, "Building a community" or "Measuring success"). They may contain visuals and anecdotes to illustrate their point. While meant to be read from beginning to end, they have a table of contents to help the reader quickly skim the content and find a relevant subsection.
+- An **FAQ** tackles a complex topic where a reader is likely coming in with specific questions (for example, "The legal side of open source" or "Leadership & governance"). Whereas concept guides aim to teach the entire concept, an FAQ respects a reader's desire to jump around, get the information they need, and leave. The table of contents is especially important in an FAQ, because the page isn't meant to be read from beginning to end. FAQs might also be longer than a concept guide, because of the jump-around navigation.
 
-Concept guides dive deep into a specific topic (for example, "Building a community" or "Measuring success"). They may contain visuals and anecdotes to illustrate their point. While meant to be read from beginning to end, they have a table of contents to help the reader quickly skim the content and find a relevant subsection.
-
-## FAQ
-
-An FAQ tackles a complex topic where a reader is likely coming in with specific questions (for example, "The legal side of open source" or "Leadership & governance"). Whereas concept guides aim to teach the entire concept, an FAQ respects a reader's desire to jump around, get the information they need, and leave. The table of contents is especially important in an FAQ, because the page isn't meant to be read from beginning to end. FAQs might also be longer than a concept guide, because of the jump-around navigation.
-
-## Design Elements
+## Design elements
 
 If you're writing a concept guide, here are some smaller design elements that enrich the content experience. We use them to draw the reader's attention and break up walls of text; therefore, they should all get some sort of visual treatment.
 
-## Pull quote
+### Pull quote
 
 We use quotes in the guide to illustrate a point through an anecdote. Pull quotes should highlight real people and their experiences.
 
-## Image
+### Image
 
 Images help visually illustrate a point. Some images are instructive, such as a graph. Other images are visual, such as a webpage screenshot. We should have lots of these.
 
-## Data vignette
+### Data vignette
 
 Whereas pull quotes and images help ground ideas in something specific and concrete, data vignettes help connect ideas to bigger systems.
 
 Data vignettes are limited so as not to overwhelm, but contain just enough information to help readers understand why they should pay attention to a certain idea.
 
-## Historical vignette
+### Historical vignette
 
 Historical vignettes are fun anecdotes that keep a reader's attention. They make community members the heroes of the story, and help pass down cultural knowledge.
+
+### List
+
+We use bulleted lists to keep articles approachable and skim-able, and to group examples and checklists. However, avoid:
+
+- Articles consisting almost entirely of lists; lists should enhance narrative rather than serve as the main attraction.
+- Exhaustive or canonical lists; follows from above. If such a list is relevant, [link](styleguide.md#content-principles) to one maintained elsewhere.
+- Lists consisting of only links; a guide is not an awesome list. Check out how we link to the main awesome list in a list, [for example](https://opensource.guide/how-to-contribute/#you-dont-just-have-to-work-on-software-projects).

docs/personas.md

@@ -14,13 +14,13 @@
 
 * Has never open sourced a project before
 
-### Primary Goals
+### Primary goals
 
 * Wants people to notice their project
 
 * Wants people to actually use the project and give feedback
 
-### Frustrations/Pain Points
+### Frustrations/pain points
 
 * Doesn't know how to find an audience
 
@@ -40,13 +40,13 @@
 
 * Likely manages projects on their own time (volunteer work)
 
-### Primary Goals
+### Primary goals
 
 * Manage personal time so project demands don't become overwhelming
 
 * Find other contributors or maintainers to help with the project
 
-### Frustrations/Pain Points
+### Frustrations/pain points
 
 * Feeling burned out, exhausted from open source work
 
@@ -66,13 +66,13 @@
 
 * Likely manages projects on their own time (volunteer work)
 
-### Primary Goals
+### Primary goals
 
 * Get people to participate, contribute back to the project
 
 * Make sure everybody involved with the project is happy and has a good experience
 
-### Frustrations/Pain Points
+### Frustrations/pain points
 
 * Managing a community is exhausting, especially when it's volunteer work
 
@@ -92,15 +92,15 @@
 
 * Cares about fostering a healthy community, but does not necessarily want to share ownership in a formal capacity
 
-### Primary Goals
+### Primary goals
 
 * Improve brand and reputation
 
     * Attract new technical talent for recruiting (make sure people hear about it)
 
 * Grow a platform (get people to use it)
 
-### Frustrations/Pain Points
+### Frustrations/pain points
 
 * Balancing community + corporate needs
 

docs/styleguide.md

@@ -8,7 +8,7 @@ From the GitHub Manual of Style, which this style guide inherits from:
 
 Where possible, [automated tests](../test/prose) enforce style rules.
 
-## Content Principles
+## Content principles
 All written content should follow these principles:
 
 * **Approachability:** Don't assume reader has prior knowledge
@@ -36,3 +36,7 @@ When referring to a project on GitHub, link to the repository so others can dive
 - :smile: Welcome to Open Source Guides!
 - :smile: The guide is meant to..
 - :cry: The goal of this Guide is to...
+
+## More guidance
+
+Understand our [content model](content-model.md) and [audience](personas.md)

docs/translations.md

@@ -17,3 +17,21 @@ If there's not, then today is your day to lead this effort! Here's how to start:
 1. Send a pull request.
 
 Completing an initial translation of the whole site is a fairly large task. One way to break that task up is to work with other translators through pull requests on your fork. Example: [pull requests on fork for German translation](https://github.com/katrinleinweber/opensource.guide/pulls?q=is%3Apr+is%3Aclosed) and corresponding [initial pull request for German translation](https://github.com/github/opensource.guide/pull/577) on this repository.
+
+## Updatng a translation
+
+### Corrections
+
+If you notice spelling or grammar errors, typos, or opportunities for better phrasing, open a pull request with your suggested fix. If you see a problem that you aren't sure of or don't have time to fix, open an issue.
+
+### Broken links
+
+When tests find broken links, try to fix them across all translations. Ideally, [only update the linked URLs](https://github.com/github/opensource.guide/pull/880/files), so that translation changes will definitely not be necessary.
+
+### Article updates
+
+We're collecting [tips](https://github.com/github/opensource.guide/issues/1119) on how to check if a translation should be updated to account for improvements made to the English source articles.
+
+### New articles
+
+New articles are rare! When we have one, we'll probably do [some form](https://github.com/github/opensource.guide/issues/1120) of a call for translations.