How to create a shout out blog post

Giving a "shout-out" means to give recognition to a contributor of Hoodie’s community. Giving recognition is very important to us and we want to get better at it, but it also comes with several pitfalls that we have to keep in mind

• Every contribution counts. There is a human behind every contribution, and behind every human is a story. We do not judge if one contribution is worth more than another, it does not matter. It’s not about creating a competition of who contributes the most, but about creating a space where everyone is appreciated.
• While many of us are good at automating things, showing appreciation is not something we want to automate, ever. It is true that there is lots of room for improvement to help us find out who contributed something, but in the end, there should be a human being from the Hoodie community who uses the tools and decides how to phrase the shout-outs. We can write tools to make contributions more visible, but appreciation cannot be automated, otherwise it looses its value.

Read more about this and other topics on the Wecloming Communities blog post.

Current state

Here is an example shout-out blog post: http://hood.ie/blog/shoutouts-week-24.html

The current state of creating a shout-out blog post is pretty tedious. We have a tool that helps a little bit, but it still requires a lot of labors. Our goal is to eventually follow a regular schedule, but we don’t yet have a team in charge for that, and we probably need to improve the tools. Right now it takes me about 2h to create a shout out blog post

Kinds of contributions

• code
  • merged pull requests, extra shout-out to first time contributors, double shout-out to first-time Open Source contributors
• comments (bug reports, helpful comments)

Tools

We currently only have one tool that helps us, github-shoutouts, follow the instructions in the README to install it. Create a GitHub token, give it a description like "GitHub Shoutouts", you don’t need to give it any access. Once you create it copy the token somewhere safe, you will need it later.

Run the script like this

SHOUTOUT_GH_TOKEN=<your token here> github-shoutouts hoodiehq

It will ask you to set the starting date/time. Set it to the date when the last shout-out blog post was published.

When the script finished, it will create a file like shoutouts-2016-07-12.md in the current directory you run it in. This is your starting point

If you have any ideas on how we cam improve this tool, create an issue. Your ideas are more than welcome.

Step by Step

1. Open the shoutouts-*.md file created by github-shoutouts (see above)

2. Add the outline of the blog post to the top of the file (or create a new one, as you like)

   <summary here>
   
   ### Backers and Sponsors
   
   List current backers and sponsors from https://opencollective.com/hoodie
   
   ### New Contributors
   
   <intro and list of new contributors sorted by name. Start with first-time Open Source contributors, then list new contributors to Hoodie>
   
   ### New Contributions to Hoodie
   
   <list of contributions by contributor, sorted by name>
   
   ### Thanks to our maintainers
   
   Thanks to our maintainers, who review all kinds of new contributions before they make their way to our code, documentation or website <3
   
   <list of people who reviewed pull request and help maintain the community in other ways>
   
   ### Special thanks
   
   <give extra shoutouts to things you want to highlight, see the [Special Thanks section of this shout out blog post](http://hood.ie/blog/shoutouts-week-24.html) as an example. Don’t worry about repeating yourself. Ask around if people have suggestions to whom they want to give shout outs to and for what. This is your stage, trust your guts, there is little you can make wrong here. And if you realise you forgot someone, make sure they get a shout out in the next blog post
   

3. Open Hoodie’s OpenCollective Page and list all current backers & sponsors in the Backers and Sponsors section.

4. Search for First PR on the hoodie project! in the shoutouts-*.md file. These are the people who contributed to Hoodie for the first time. To find out if their contribution was the the first on GitHub in general, go to http://firstpr.me/ and enter their username. Fill in their contributions to the ### New Contributors section. Also check if some of the new backers and sponsors are new to the Hoodie community, in that case welcome them here as well! If the GitHub users provided their real names on their GitHub profile page, use them in the shoutouts, otherwise use the username.

5. Search for reviewed in the shoutouts-*.md file. Everyone who reviewed a pull request helped to maintain the Hoodie community. List them all in the Thanks to our maintainers section. Lookup their names and use that.

6. Now go through all contributors, look for landed. Write a sentence or two for everyone who landed a pull request and link to the pull requests

7. Ask around in the community what was special in the community since the last shout out blog post and write it down in the Special Thanks section.

Tips

• use emoji. Everything can be better with emoji :) Check out Kent C. Dodds’ all-contributors for ideas what emjoi to use to highlight different contributions