Skip to content

Replace fancy quotes with plain ol' boring quotes #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 18, 2016
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Open Source Handbook

This handbook is a collection of resources to help individuals, communities, and companies sustainably embrace open source software. It explains not only how to accomplish a task, but why youd want to, and how that task fits into the larger story of consuming, contributing to, and producing open source software.
This handbook is a collection of resources to help individuals, communities, and companies sustainably embrace open source software. It explains not only how to accomplish a task, but why you'd want to, and how that task fits into the larger story of consuming, contributing to, and producing open source software.

This handbook aims to foster healthy open source communities, and provide a canonical place for the community to discuss and codify best practices into highly-approachable resources.

Expand Down
32 changes: 15 additions & 17 deletions docs/content-model.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Content Model

The Open Source Handbook helps individuals, communities, and companies embrace open source software. It explains not only how to accomplish a task, but why youd want to, and how that task fits into the larger story of consuming, contributing to, and producing open source software.
The Open Source Handbook helps individuals, communities, and companies embrace open source software. It explains not only how to accomplish a task, but why you'd want to, and how that task fits into the larger story of consuming, contributing to, and producing open source software.

This content is created and curated by GitHub, and covers topics that are very relevant to GitHub users, but it is not specific to GitHub products.

Expand All @@ -13,22 +13,22 @@ For content that is specific to GitHub products, see:

Each piece of content is grouped under a *dimension* and *topic*.

A *dimension* roughly describes an individuals relationship with an open source project:
A *dimension* roughly describes an individual's relationship with an open source project:

0. **Basics**: rudimentary introduction to the concepts of open source.
0. (coming in v2) **Consuming**: using open source software.
0. (coming in v2) **Contributing**: getting involved and improving existing open source projects.
0: **Producing**: starting, growing, and maintaining your own open source project.

A topic groups together content around a high-level goal of the user, and should begin with a [gerund](https://en.wikipedia.org/wiki/Gerund).
A "topic" groups together content around a high-level goal of the user, and should begin with a [gerund](https://en.wikipedia.org/wiki/Gerund).

Examples:

- :smile: Building a community
- :smile: Reviewing contributions
- :smile: Choosing a license
- :cry: Code review
- :cry: Legal
- :smile: "Building a community"
- :smile: "Reviewing contributions"
- :smile: "Choosing a license"
- :cry: "Code review"
- :cry: "Legal"

## Common Elements

Expand All @@ -39,7 +39,7 @@ Every piece of content contains these elements:
Each piece of content may also include:

- [References](#references)
- [Credits](#credits) -
- [Credits](#credits) -

### Introductions

Expand Down Expand Up @@ -92,23 +92,23 @@ Tactical content answers the question "How?". This is arguably the most common t

Tactical content is structured as:

- **Title** - Tactical articles should begin with a gerund. For example, "Enforcing a code of conduct.
- **Title** - Tactical articles should begin with a gerund. For example, "Enforcing a code of conduct".

- **Introduction** - The introduction should should explain what the user will specifically accomplish by applying these tactics, and can and probably should reference [conceptual content](#conceptual-content) to further explain why you would want to apply the tactics. For example, an article on Enforcing a Code of Conduct should reference the conceptual content About codes of conduct.
- **Introduction** - The introduction should should explain what the user will specifically accomplish by applying these tactics, and can and probably should reference [conceptual content](#conceptual-content) to further explain why you would want to apply the tactics. For example, an article on "Enforcing a Code of Conduct" should reference the conceptual content "About codes of conduct".

- **Tactical sections** - These sections explain each tactic involved in achieving the goal. They may be procedural steps, or just a list of individual tactics that should be considered. For example, an article on Enforcing a code of conduct might have a tactical section called Responding to reports of abuse.
- **Tactical sections** - These sections explain each tactic involved in achieving the goal. They may be procedural steps, or just a list of individual tactics that should be considered. For example, an article on "Enforcing a code of conduct" might have a tactical section called "Responding to reports of abuse".

- **Summarizing conclusion** - Conclude by briefly reviewing how these tactics connect to the larger story and encouraging the user to find ways to apply them to their situation.

- Links to **Related content** - Hopefully the user is excited about what they've just learned and wants to find out more.

### Frequently Asked Questions (FAQs)

FAQ articles aim to directly address common questions or misconceptions. These tend to be questions that have known but nuanced answers, such as Is open source software secure? or How do I convince my boss to let me contribute to open source?.
FAQ articles aim to directly address common questions or misconceptions. These tend to be questions that have known but nuanced answers, such as "Is open source software secure?" or "How do I convince my boss to let me contribute to open source?".

FAQ content is structured as:

- **Title** should be in the form of a question. The question should be succinct and as close to the most widely asked form of the question, because not every person will ask a question in the same way. For example, What is open source?, or How do I make money writing open source software?
- **Title** should be in the form of a question. The question should be succinct and as close to the most widely asked form of the question, because not every person will ask a question in the same way. For example, "What is open source?", or "How do I make money writing open source software?"

- **Body** should be as brief as possible - answering the question and linking off to more information where appropriate. Ask yourself if the question (the title) could be rephrased to create [conceptual](#conceptual-content) or [tactical](#tactical-content) content.

Expand All @@ -124,5 +124,3 @@ Referential content is structured as:
- **Title** - should begin with a noun describing the information that's being referenced, followed by how you'd use that thing. For example, "Countries that support SMS for two-factor authentication".

It's always a good idea to link a referential article to a tactical or conceptual article, even if that's in the **Further reading** section at the end of the article.


12 changes: 6 additions & 6 deletions docs/personas.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@

### Frustrations/Pain Points

* Doesnt know how to find an audience
* Doesn't know how to find an audience

## 2. Individual developer (multiple projects)

Expand All @@ -42,7 +42,7 @@

### Primary Goals

* Manage personal time so project demands dont become overwhelming
* Manage personal time so project demands don't become overwhelming

* Find other contributors or maintainers to help with the project

Expand Down Expand Up @@ -74,7 +74,7 @@

### Frustrations/Pain Points

* Managing a community is exhausting, especially when its volunteer work
* Managing a community is exhausting, especially when it's volunteer work

## 4. Corporate entity

Expand Down Expand Up @@ -114,12 +114,12 @@

* Non-developers (individual, student, community, corporate)

* People who are open sourcing projects that dont involve code (ex. books, documents, templates)
* People who are open sourcing projects that don't involve code (ex. books, documents, templates)

* Can we use language that applies to both code- and non-code-centric projects?

* If we dont tailor the handbook to them, will they feel isolated or ignored? Is there anything wed miss about their experience?
* If we don't tailor the handbook to them, will they feel isolated or ignored? Is there anything we'd miss about their experience?

* Student developer

* Likely more interested in learning how to contribute vs. how to start their own project. Set this aside for v1 (were primarily focusing on who produces open source projects)
* Likely more interested in learning how to contribute vs. how to start their own project. Set this aside for v1 (we're primarily focusing on who produces open source projects)
24 changes: 12 additions & 12 deletions getting-started/branding.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,45 +3,45 @@ title: Branding
next: getting-started/preparing.md
---

Youve thought about who your users are, what they need from you, and what you might be able to offer them. Next, well put that research into practice as we consider the brand of your project.
You've thought about who your users are, what they need from you, and what you might be able to offer them. Next, we'll put that research into practice as we consider the brand of your project.

Branding may sound like a waste of time. After all there, are plenty of popular open source projects that have never thought about their brand at all.

But branding is more than a flashy logo or catchy project name. Its about how you talk about your project and who you reach with your message. Here are a few things youll want to think about before you launch.
But branding is more than a flashy logo or catchy project name. It's about how you talk about your project and who you reach with your message. Here are a few things you'll want to think about before you launch.

## Choosing the right name

Pick a name that is easy to remember and, ideally, gives some idea of what the project does. For example, [Sentry](https://github.com/getsentry/sentry) monitors apps for crash reporting, and [Thin](https://github.com/macournoyer/thin) is a fast and simple Ruby web server.

Consider clarity above all. Puns are fun, but remember that some jokes might not translate to other cultures or people with different experiences from you. For example, some of your users might be employees; you dont want to make them uncomfortable when they have to explain your projects name to coworkers!
Consider clarity above all. Puns are fun, but remember that some jokes might not translate to other cultures or people with different experiences from you. For example, some of your users might be employees; you don't want to make them uncomfortable when they have to explain your project's name to coworkers!

## Avoiding name conflicts

Make sure that your projects name doesnt infringe upon any trademarks. A company might ask you to take down your project later on, or even take legal action against you. Its just not worth the risk. You can check for U.S. trademark conflicts [here](http://www.uspto.gov/trademarks-application-process/search-trademark-database). If youre at a company, this is one of the things your [legal team can help you with](../legal/#what-does-my-companys-legal-team-need-to-know).
Make sure that your project's name doesn't infringe upon any trademarks. A company might ask you to take down your project later on, or even take legal action against you. It's just not worth the risk. You can check for U.S. trademark conflicts [here](http://www.uspto.gov/trademarks-application-process/search-trademark-database). If you're at a company, this is one of the things your [legal team can help you with](../legal/#what-does-my-companys-legal-team-need-to-know).

Youll also want to look for open source projects with a similar name, especially if you share the same language or ecosystem. If your name overlaps with a popular existing project, you will confuse your audience and make it less likely that anyone will use what youve created. You can check for similar project names [here](http://ivantomic.com/projects/ospnc/).
You'll also want to look for open source projects with a similar name, especially if you share the same language or ecosystem. If your name overlaps with a popular existing project, you will confuse your audience and make it less likely that anyone will use what you've created. You can check for similar project names [here](http://ivantomic.com/projects/ospnc/).

Consider whether youll want a website, Twitter handle, or other properties to represent your project. If so, make sure you can get the names you want. Ideally, reserve those names now so you have peace of mind. You can check for domain name availability [here](https://instantdomainsearch.com/).
Consider whether you'll want a website, Twitter handle, or other properties to represent your project. If so, make sure you can get the names you want. Ideally, reserve those names now so you have peace of mind. You can check for domain name availability [here](https://instantdomainsearch.com/).

Finally, it doesnt hurt to do a quick Google search for your project name. Will people be able to easily find your project? Does something else appear in the search results that you wouldnt want them to see?
Finally, it doesn't hurt to do a quick Google search for your project name. Will people be able to easily find your project? Does something else appear in the search results that you wouldn't want them to see?

## How you write (and code) affects your brand, too!

Throughout the life of your project, youll do a lot of writing: READMEs, tutorials, community documents, responding to issues, maybe even newsletters and mailing lists. Whether its official documentation or a casual email, how you write contributes to the brand of a project. Consider how you might come across to your audience and whether that is the tone you wish to convey.
Throughout the life of your project, you'll do a lot of writing: READMEs, tutorials, community documents, responding to issues, maybe even newsletters and mailing lists. Whether it's official documentation or a casual email, how you write contributes to the brand of a project. Consider how you might come across to your audience and whether that is the tone you wish to convey.

@janl discovered that the way he spoke to others helped create a positive brand for [CouchDB](https://github.com/apache/couchdb):

> When I started out at CouchDB and we finally joined the ASF \[Apache Software Foundation\] and it was standard procedure to have a user@ mailing list for end-user support, I remembered my days in the #php channel and decided that thats not the culture I want to have there. So for the first three or so years, I tried to be involved with every thread on the mailing list, and showing exemplary behaviour, being nice to people, taking their issues seriously and trying to be helpful overall. After a while, people stuck around not to only ask questions, but to help with the answering as well, and to my complete delight, they mimicked my style. \[...\]
> When I started out at CouchDB and we finally joined the ASF \[Apache Software Foundation\] and it was standard procedure to have a user@ mailing list for end-user support, I remembered my days in the #php channel and decided that that's not the culture I want to have there. So for the first three or so years, I tried to be involved with every thread on the mailing list, and showing exemplary behaviour, being nice to people, taking their issues seriously and trying to be helpful overall. After a while, people stuck around not to only ask questions, but to help with the answering as well, and to my complete delight, they mimicked my style. \[...\]
>
> Every time I join and read, I see the culture that I helped plant there seven years ago and it makes me very proud. [^1]

[^1]: [Sustainable Open Source](http://writing.jan.io/2015/11/20/sustainable-open-source.html) by @janl

Beyond how you write words, your coding style may also become part of your projects brand. For example, [Angular](https://github.com/johnpapa/angular-styleguide) and [jQuery](http://contribute.jquery.org/style-guide/js/) are two projects with rigorous coding styles and guidelines.
Beyond how you write words, your coding style may also become part of your project's brand. For example, [Angular](https://github.com/johnpapa/angular-styleguide) and [jQuery](http://contribute.jquery.org/style-guide/js/) are two projects with rigorous coding styles and guidelines.

It isnt necessary to write a style guide for your project when youre just starting out, and you may find that you enjoy incorporating different coding styles into your project anyway. But you should anticipate how your writing (and coding) style might attract (or not attract) different types of people. The earliest stages of your project are your opportunity to set the precedent you wish to see.
It isn't necessary to write a style guide for your project when you're just starting out, and you may find that you enjoy incorporating different coding styles into your project anyway. But you should anticipate how your writing (and coding) style might attract (or not attract) different types of people. The earliest stages of your project are your opportunity to set the precedent you wish to see.

Were almost there! Next, well walk you through a few components that every open source project should include when you launch.
We're almost there! Next, we'll walk you through a few components that every open source project should include when you launch.

## Further reading

Expand Down
Loading