Skip to content

Use footnote references #24

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.

Sign up for GitHub

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 2 commits into from
Aug 13, 2016
Merged

Use footnote references #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f8ce4b0
Enable GFM and footnotes in linter
bkeepers Aug 13, 2016
1898a6d
Use proper footnote references
bkeepers Aug 13, 2016
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
10 changes: 4 additions & 6 deletions getting-started/branding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,20 +31,18 @@ Throughout the life of your project, you’ll do a lot of writing: READMEs, tuto

[@janl](https://github.com/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 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. [...]*
> 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]

*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](https://github.com/janl)

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 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.

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

## Footnotes

[1] [http://writing.jan.io/2015/11/20/sustainable-open-source.html](http://writing.jan.io/2015/11/20/sustainable-open-source.html)

## Further reading

* [http://producingoss.com/en/getting-started.html#choosing-a-name](http://producingoss.com/en/getting-started.html#choosing-a-name)
18 changes: 8 additions & 10 deletions marketing/building-community.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,17 @@ Documenting your open source project means more than just technical documentatio

As you promote your project, people will probably have feedback and ideas for you. They may request support or functionality, have questions about how things work, or need help getting started.

Try to be responsive when someone files an issue, submits a pull request, or asks a question about your project. When you respond quickly, people will feel they are part of a dialogue, and feel more enthusiastic about participating in and using your project. For example, when Mozilla studied its community and engagement in 2014, they found that contributors who received code reviews within 48 hours had a much higher rate of return and repeat contribution. [1]
Try to be responsive when someone files an issue, submits a pull request, or asks a question about your project. When you respond quickly, people will feel they are part of a dialogue, and feel more enthusiastic about participating in and using your project. For example, when Mozilla studied its community and engagement in 2014, they found that contributors who received code reviews within 48 hours had a much higher rate of return and repeat contribution.[^1]

[^1]: https://docs.google.com/presentation/d/1hsJLv1ieSqtXBzd5YZusY-mB8e1VJzaeOmh8Q4VeMio/edit#slide=id.g43d857af8_0177

Remember that conversations about your project could also be happening in other places around the Internet, such as Stack Overflow, Twitter, or Reddit. You can set up notifications in some of these places so you are alerted when someone mentions your project.

## Make it easy for people to use and contribute

One way to think about your project’s community is what [@MikeMcQuaid](https://github.com/MikeMcQuaid) calls the contributor funnel. [2] At the top of the funnel is anybody who could potentially use your project. At the bottom of the funnel are people like you who maintain the project.
One way to think about your project’s community is what [@MikeMcQuaid](https://github.com/MikeMcQuaid) calls the contributor funnel. [^2] At the top of the funnel is anybody who could potentially use your project. At the bottom of the funnel are people like you who maintain the project.

[^2]: https://speakerdeck.com/mikemcquaid/the-open-source-contributor-funnel

As you build your community, consider how someone at the top of the funnel (a potential user) might theoretically make their way to the bottom (an active maintainer). Your goal is to make each stage of the contributor experience as frictionless as possible. When people have easy wins, they will feel incentivized to do more.

Expand All @@ -47,17 +51,11 @@ For casual or first-time contributors, be open-minded about the types of contrib

You’re doing great so far! Now that you’re promoting your project and growing a community, you’re probably wondering whether you’re doing it right. In the next section, we’ll talk about metrics to measure your project’s success and how to track them.

## Footnotes

[1] [https://docs.google.com/presentation/d/1hsJLv1ieSqtXBzd5YZusY-mB8e1VJzaeOmh8Q4VeMio/edit#slide=id.g43d857af8_0177](https://docs.google.com/presentation/d/1hsJLv1ieSqtXBzd5YZusY-mB8e1VJzaeOmh8Q4VeMio/edit#slide=id.g43d857af8_0177)

[2] [https://speakerdeck.com/mikemcquaid/the-open-source-contributor-funnel](https://speakerdeck.com/mikemcquaid/the-open-source-contributor-funnel)

## Further reading

* [http://radek.io/2015/10/12/marketing-for-open-source-projects-5/](http://radek.io/2015/10/12/marketing-for-open-source-projects-5/)
* [http://radek.io/2015/10/12/marketing-for-open-source-projects-5/](http://radek.io/2015/10/12/marketing-for-open-source-projects-5/)

* [http://hood.ie/blog/welcoming-communities.html](http://hood.ie/blog/welcoming-communities.html)
* [http://hood.ie/blog/welcoming-communities.html](http://hood.ie/blog/welcoming-communities.html)

* [https://ashfurrow.com/blog/building-popular-projects/](https://ashfurrow.com/blog/building-popular-projects/)

Expand Down
18 changes: 8 additions & 10 deletions marketing/spreading-word.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,9 @@ There is no magical formula to building an audience and reputation. Gaining the

You can help people find and remember you by pointing them to your project’s namespace—a website, Twitter handle, or IRC channel, for example.

Consider creating a website for your project. [@adrianholovaty](https://github.com/adrianholovaty) called a well-designed site "by far the best thing we did with Django in the early days". [1] [Yeoman](http://yeoman.io/), [Vagrant](https://www.vagrantup.com/), and [Middleman](https://middlemanapp.com/) are a few more examples of excellent, comprehensive websites.
Consider creating a website for your project. [@adrianholovaty](https://github.com/adrianholovaty) called a well-designed site "by far the best thing we did with Django in the early days"[^1]. [Yeoman](http://yeoman.io/), [Vagrant](https://www.vagrantup.com/), and [Middleman](https://middlemanapp.com/) are a few more examples of excellent, comprehensive websites.

[^1]: https://news.ycombinator.com/item?id=7531689

A website, along with clear documentation and tutorials, makes your project seem friendly and easy to navigate. It also suggests that your project is active and supported, which will make your audience feel more comfortable using it. Adding tutorials and examples gives people ideas for ways they can use your project.

Expand All @@ -37,7 +39,9 @@ Consider introducing yourself and your work to related open source projects and

## Go where your audience is (offline)

Look for meetups and conferences that are relevant to your work. Offline outreach is a great way to reach an engaged audience and build deeper human connections, especially if you are interested in reaching developers. [@mitchellh](https://github.com/mitchellh) attributes [Vagrant](https://github.com/mitchellh/vagrant)’s growth and popularity to the talks he gave about the project. [2]
Look for meetups and conferences that are relevant to your work. Offline outreach is a great way to reach an engaged audience and build deeper human connections, especially if you are interested in reaching developers. [@mitchellh](https://github.com/mitchellh) attributes [Vagrant](https://github.com/mitchellh/vagrant)’s growth and popularity to the talks he gave about the project. [^2]

[^2]: https://github.com/swinton/codeconf/blob/master/the-hashicorp-formula-to-open-source.md

If you’re new to public speaking, start by finding a local meetup that’s related to the language or ecosystem of your project. If you’ve never spoken at an event before, it’s perfectly normal to feel nervous! Remember that your audience is there because they genuinely want to hear about your work. As you design your talk, remember to focus on what your audience will find interesting and get value out of. Keep your language friendly and approachable. Smile, breathe, and have fun.

Expand All @@ -47,17 +51,11 @@ Spreading the word is an important step in growing the popularity of your projec

In the next section, we’ll talk about how to retain those early enthusiasts and grow an engaged community around your project.

## Footnotes

[1] [https://news.ycombinator.com/item?id=7531689](https://news.ycombinator.com/item?id=7531689)

[2] [https://github.com/swinton/codeconf/blob/master/the-hashicorp-formula-to-open-source.md](https://github.com/swinton/codeconf/blob/master/the-hashicorp-formula-to-open-source.md)

## Further reading

* [https://hacks.mozilla.org/2013/05/how-to-spread-the-word-about-your-code/](https://hacks.mozilla.org/2013/05/how-to-spread-the-word-about-your-code/)
* [https://hacks.mozilla.org/2013/05/how-to-spread-the-word-about-your-code/](https://hacks.mozilla.org/2013/05/how-to-spread-the-word-about-your-code/)

* [https://zachholman.com/posts/open-source-marketing/](https://zachholman.com/posts/open-source-marketing/)
* [https://zachholman.com/posts/open-source-marketing/](https://zachholman.com/posts/open-source-marketing/)

* [http://readwrite.com/2014/10/10/open-source-marketing-apache-storm-nathan-merz/](http://readwrite.com/2014/10/10/open-source-marketing-apache-storm-nathan-merz/)

Expand Down
8 changes: 7 additions & 1 deletion script/test-prose
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@ var jekyllConfig = yaml.safeLoad(fs.readFileSync('_config.yml', 'utf8'));
var ignore = require('ignore')().add(jekyllConfig["exclude"])

var options = {
// https://github.com/wooorm/remark/tree/master/packages/remark-parse#options
"remark": {
"gfm": true,
"footnotes": true
},

// https://github.com/wooorm/remark-lint/blob/master/doc/rules.md
"lint": {
"list-item-indent": "space", // As the gods intended.
Expand Down Expand Up @@ -55,7 +61,7 @@ async.map(ignore.filter(glob.sync("**/*.md")), function(file, callback) {
// .use(require('retext-readability'), options["readability"])
// )
.use(stringify)
.process(contents.toString(), function (err, result) {
.process(contents.toString(), options["remark"], function (err, result) {
result.filename = file;
callback(err, result);
});
Expand Down
22 changes: 10 additions & 12 deletions sustaining/best-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@ Be honest with yourself about how much time you have to spend on your project. T

Write down your project’s vision and, where possible, make that vision transparent to others. Your vision is your North Star, guiding you when you feel overwhelmed by others’ requests, and helping you reset your priorities. Add it to your README. If there are related artifacts that you think could help, like a project roadmap, make those public as well.

[@lord](https://github.com/lord) discovered that having a project vision helped him figure out which requests he should spend time on. As a new maintainer, he regretted not sticking to his project’s scope when he got his first feature request for [Slate](https://github.com/lord/slate): *"I fumbled it. I didn’t put in the effort to come up with a complete solution. Instead of an half-assed solution, I wish I had said “I don’t have time for this right now, but I’ll add it to the long term nice-to-have list."* [1]
[@lord](https://github.com/lord) discovered that having a project vision helped him figure out which requests he should spend time on. As a new maintainer, he regretted not sticking to his project’s scope when he got his first feature request for [Slate](https://github.com/lord/slate): *"I fumbled it. I didn’t put in the effort to come up with a complete solution. Instead of an half-assed solution, I wish I had said “I don’t have time for this right now, but I’ll add it to the long term nice-to-have list."* [^1]

[^1]: [https://lord.io/blog/2014/oss-tips/](https://lord.io/blog/2014/oss-tips/)

These types of exercises may seem trivial, but the more you know yourself and your limits (not just abilities!), the easier it is to say no to things that don’t fit into your scope.

Expand All @@ -41,15 +43,19 @@ Some examples of rules you may want to write down:

## Learn to say no

The first rule of open source, according to [@shykes](https://github.com/shykes): *"No is temporary, yes is forever."* [2] If you plan on maintaining open source projects for a long time, it’s never too early to practice saying no.
The first rule of open source, according to [@shykes](https://github.com/shykes): *"No is temporary, yes is forever."* [^2] If you plan on maintaining open source projects for a long time, it’s never too early to practice saying no.

[^2]: [https://twitter.com/solomonstre/status/715277134978113536](https://twitter.com/solomonstre/status/715277134978113536)

Saying no applies to many situations you’ll come across as a maintainer. You can say no to feature requests that don’t fit the scope of your project. You can say no, or refuse to engage, when someone derails a conversation on a mailing list. You can say no to doing work for others that you don’t find important.

One of the most important places you’ll practice saying no is on your your issue and pull request queue. If someone suggests an idea that you know you won’t accept, don’t leave it open because you feel guilty or want to be nice. Be kind, but firm. Thank them for their contribution and explain why it doesn’t fit into the scope of the project. Then close the request.

If you notice repeated requests for things you don’t want to accept, consider adding them into your contribution policy, so you don’t have to keep repeating yourself.

If the thought of saying no terrifies you, you’re not alone. As [@jfrazelle](https://github.com/jfrazelle) put it: *"I’ve talked to maintainers from several different open source projects, Mesos, Kubernetes, C**hromium**, and they all agree one of the hardest parts of being a maintainer is saying “No" to patches you don’t want.”* [3] But the more often you practice saying no, the easier it becomes. Promise.
If the thought of saying no terrifies you, you’re not alone. As [@jfrazelle](https://github.com/jfrazelle) put it: *"I’ve talked to maintainers from several different open source projects, Mesos, Kubernetes, C**hromium**, and they all agree one of the hardest parts of being a maintainer is saying “No" to patches you don’t want.”* [^3] But the more often you practice saying no, the easier it becomes. Promise.

[^3]: [https://blog.jessfraz.com/post/the-art-of-closing/](https://blog.jessfraz.com/post/the-art-of-closing/)

## Keep communication public

Expand All @@ -69,7 +75,7 @@ The good news about maintaining a popular open source project is that other main

* [Vossibility](https://github.com/icecrime/vossibility-stack) pulls stats on your project

* [mention-bot ](https://github.com/facebook/mention-bot)automatically mentions potential reviewers for pull requests
* [mention-bot](https://github.com/facebook/mention-bot)automatically mentions potential reviewers for pull requests

* [PullApprove](https://about.pullapprove.com/) helps you manage pull requests

Expand All @@ -81,14 +87,6 @@ If you want to get a little more advanced, style guides and linters can help sta

Hopefully, you’re feeling more empowered to say no, set and enforce rules, and take breaks when you need them. In the next section, we’ll talk about how you can leverage your community to grow a sustainable project.

## Footnotes

[1] [https://lord.io/blog/2014/oss-tips/](https://lord.io/blog/2014/oss-tips/)

[2] [https://twitter.com/solomonstre/status/715277134978113536](https://twitter.com/solomonstre/status/715277134978113536)

[3] [https://blog.jessfraz.com/post/the-art-of-closing/](https://blog.jessfraz.com/post/the-art-of-closing/)

## Further reading

* [http://www.kennethreitz.org/essays/be-cordial-or-be-on-your-way](http://www.kennethreitz.org/essays/be-cordial-or-be-on-your-way)
Expand Down
Loading