CONTENT: /contributors

[jennwrites]

Per hoodiehq/discussion#90
Part of #49

We need a contributor to help create copy for a landing page for new and existing contributors (currently at http://hood.ie/contribute/). It would be like docs.hood.ie, but documentation for contributors, not users.

We could document conventions like how we create READMEs, how we prepare issues to make them "starter" issues, what tools we use, why, and how, we could make tutorials where we go through the code base explaining how things work together. And all this for both, code & editorial contributors, of course.

You would be coordinating and collaborating with @gr2m

This would be an ongoing effort, so multiple contributors can help!

---

UPDATE: APRIL 5 @gr2m and I (@rubymorillo) spoke about the content and discussed a few considerations which would widen the scope for this project. Here's a summary of what was discussed below:

• The contributors page is envisioned as a standalone site (a single page app, perhaps?). The goal is for it to have all of the information people would need without being restrained by the format of the current site.
• The goals of this page are to 1. Provide documentation for contributors who are involved/want to get involved. This includes answering questions about how to become a contributor or a maintainer, and understanding the workflow of each team for ease of use. 2. Showcase the different tracks (code, design, editorial, documentation) through use of the mascots, and allow contributors to access track-specific documentation and see tickets (more below).

Possible site flow

TOP LAYER
Icons of the mascots (with track names underneath), preceded by a "get started" icon. When a user clicks on "Get Started" it'll jump to a section with general documentation that is relevant to all contributors, regardless of track.

TRACKS
When a user clicks on a track mascot, they'll jump down to that track which will have a few sections: 1. Track-specific documentation, with information about preferred Git flow, formatting, etc. 2. Existing Contributors: Issues that are available to people that have contributed before? (We didn't clear up what else could live here) and 3. New contributors: tips for new contributors and issues that are tagged with Your First PR (or another label).

Other possible elements

Something else that was discussed but we couldn't answer was: how do we showcase a place with who did what? What contributions have been made and by whom? Presently, we celebrate PRs on Twitter, but it would be great to have a place where we expand on this further; institutionalizing appreciation for contributors in general. We aren't sure if this /contributors page is the best place for it, so that's a question we wanted to throw out to the team.

Final things to consider

We talked about how people frequently ask "How do I become a contributor?" or "How do I become a maintainer?", questions which could live on this page. Are there any other questions around contributions that could live here? If so, what?

Please add your thoughts, everyone! cc @janl @renrutnnej

---

UPDATE: APRIL 12 @jsimplicio and I (@gr2m) spoke about the information architecture and user experience of what this contributors landing page could be. Here’s a summary of what we came up with, the full log of our chat is here: https://gist.github.com/gr2m/8a22d8bd923f760831c42fd308e74400

We came up with a name for this thing: "Hoodie Camp". It resonates with me, because it makes sense with the "Hoodie Camp Release" where we decided to focus on contributors. The "Hoodie Camp" will remain after this release though as the place where all Hoodie Contributors hang out, see what is happening, who needs help, and what is up next. Also "Hoodie Camp Site" is so fantastically ambiguous :)

We came up with this overall architecture:

• Contribute
  This is where we could show open for new contributors, returning contributors, pull requests that need reviews, etc
• Roadmap & News
  Show our overall master plan (Camp / Village / City) release, what parts we currently work on, and show a log of what happened lately
• Help
  Documentation for contributors and maintainers, e.g. how to start a pull request, how to rebase / squash commits, how to create a new contributor-friendly issues, what are starter issues, etc etc etc

"Contribute" (or how ever we will call the part of the site) would be the default landing page. We could start with it and ignore the other two parts for the first version and add them later. The Contribute landing page would welcome (new) contributors and show open YFPR issue by default. I can change that to show "next step" (or non-YFPR or how-ever we want to call them) issues, or to show me issues that people are currently working on, showing me pull-request that are awaiting review, etc. So I can set a filter depending on wether I am a new contributor, a returning contributor or a maintainer / reviewer. I get an overview of open issues across all teams: code, design, documentation, editorial (sorted alphabetically ¯_(ツ)_/¯). When I’m part of the editorial team, I can dive into the "Editorial Contribute" landing page and see more issues and what ever else makes sense to display there.

Where do the issues come from?

Our idea is to create a new repository like https://github.com/hoodiehq/camp. All teams use that repository to create well-prepared issues for new and existing contributors. The idea is to bring us all together to one place, and to have a central place we can send people to instead of them getting lost in all our Hoodie repositories. The issues would have tags to differentiate between issues for new and existing contributors (maybe a single "Your First PR" label would be enough) and tags to differentiate the different kind of work like "Design", "Code", "Editorial" etc. Of course issues can have multiple team tags, too :)

Where does the Roadmap / updates / docs come from?

Roadmap can be generated out of "High level issues" and Milestones like we did at http://gr2m.github.io/milestones/, which is generated out of https://github.com/gr2m/milestones/issues. Help & Docs can be generated (or simply link to) the repositories wiki page. And latest updates can be loaded from the a special wiki page, too :)

[rubymorillo]

@renrutnnej @gr2m I'd like to work on this one!

[gr2m]

A few thoughts, nothing set in stone: we were thinking of maybe creating an entire new page for contributors, something with more of a dashboard character, aimed at new and existing contributors.

For new contributors, the page would show issues which are prepared for new contributors to work on from the different teams (Code, Design, Documentation, Editorial).

For existing contributors, it would also show things to work on, but also give an overview of what is happening right now, and what happened recently.

Does that make sense?

[rubymorillo]

Yes, this makes sense. Do we have a timeline on this?

I'm happy to jump on a call later this week so we can discuss the layout of this page(s) and where we can start work. Let me know if that works with you @gr2m and I'll reach out!

[gr2m]

let’s chat after our call on Thursday if that works for you?

[rubymorillo]

yup, sounds good @gr2m!

[jennwrites]

Hey @rubymorillo just checking in to see if you need any assistance with this ☺️

[rubymorillo]

@renrutnnej just added some notes from my call with Gregor this week in the original comment, above (It's under UPDATE APRIL 5) where we discuss the possible flow and some questions we had. I'd love your thoughts and @janl's on it!

[gr2m]

@renrutnnej @rubymorillo I had a chat with @jsimplicio on it, I think we came up with some good ideas. I updated the issue description with our thoughts and a link to our chat