Merge pull request CodeForPhilly#6 from lottspot/master

Add base sections for contributing-to-a-project.md and starting-a-project.md

contributing-to-a-project.md

@@ -0,0 +1,135 @@
+## Identifying Need
+
+#### In a nutshell
+
+The first and foremost thing to do when joining a project is to figure out what needs to be done
+for the project at the present time. Identifying what tasks need to be accomplished is the best
+way to identify how to have an immediate and helpful impact on a project as a contributor.
+
+#### Reviewing onboarding material
+
+When coming on to a new project, the best place to start is by reviewing any onboarding material.
+Commond places to find onboarding material for a project include:
+
+- README.md
+- CONTRIBUTING.md
+- Project wiki
+
+These locations often include information on how to get up and running with a development environment,
+common workflow practices, locations of issue trackers, wikis, documentation, etc, and other information
+which may be necessary in order to make contributions to the project.
+
+#### Talking to active project members
+
+Ideally, a project should have up-to-date and readily available onboarding materials for a new contributor
+to review. Unfortunately though, not all projects have this information documented and published. In cases
+such as these, it's best to reach out to current contributors to the project. Even when this documentation
+does exist, it may be necessary to reach out to active contributors to ask clarifying questions,
+correct outdated information, or just to say hello so they know who they are working with!
+
+## Communicating activity
+
+#### In a nutshell
+
+Being a good contributor means not leaving project teammates guessing. It is important that all team members
+understand what each other team member is actively doing (or not doing) so that team members can avoid stepping
+on each other's toes, while still ensuring everything that needs to be done is done.
+
+#### What your are working on
+
+Being a good contributor means letting the team know when starting work on a new task. There are never too many channels
+to keeping teammates in the loop! If the task is in the issue tracker being used by the team (which it definitely should be),
+always self-assign the task when working on it, and even inform the team via the regular communication channel, whether that
+be a chat channel or an email thread. Keeping the team aware of what tasks are being worked on not only helps the team avoid
+duplicating efforts, but also encourages the team to see tasks being worked on.
+
+#### What you are no longer working on
+
+Being a good contributor means letting the team know when work on a task has stopped or stalled. Sometimes things come up;
+a task can be blocked by another task, a teammate may no longer have time to work on a task, or may be simply burned out from
+working on a task they don't like. Under these circumstances, a contributor should always let their teammates know that the
+task is no longer being worked on, so that everyone is aware that it will need to be picked up and worked on by someone else.
+If the task is being tracked in the project issue tracker (which it definitely should be) always make sure to unassign the task
+so that no teammate believes it is still being worked on.
+
+#### When you've done a thing
+
+A lot of (personal) time gets invested in contributing to an open source project. Be proud of every little thing that gets
+accomplished! Whenever a task is accomplished or something is done for the project, let the team know via the regular communication
+channels (e.g., chat or email chain). Letting teammates know about accomplishments not only keeps them in the loop about what does
+or does not remain to be done, but helps encourage them by showing that the project is making progress! This may be one of the most
+underrated aspects of being a helpful contributor. If the task is being tracked in the project issue tracker (...you get the idea),
+always make sure to mark it as completed to keep the view of the project status current.
+
+#### Your hopes and dreams!
+
+Investing time in helping to make a project happen means that you are part of that project! As a part of that project, you shouldn't
+be shy about speaking up about your vision for its future and its mission. It's important to also remember that your vision isn't the
+only one, but contributing your opinions is important in order to continue feeling invested in the project and its mission.
+
+## Being a good citizen as a technical contributor
+
+As a technical contributor, it is important to abide by the contribution guidelines of the project. There are some general guidelines
+as well which will improve the quality of contributions to any project, and make the contributions more easily digestible by teammates.
+
+#### Atomic commits and PRs
+
+Every commit should have a specific focus and scope, and should not include work being done outside of that scope. This idea of ensuring
+that each commit remains small with all changes within the commit being related to one another can be more concisely referred to as
+and "atomic commit". Constructing commits this way makes them easier to review for teammates and makes them simpler to perform git
+operations on.
+
+#### Documentation
+
+New code should always be documented! This is a general coding best practice, but comes into particular focus when working on open source
+projects where new contibutors may frequently come and go. Contributing well documented code makes it simple for new contributors to quickly
+and easily understand work which has been previously done. Also, it makes it easy for current contributors to remember how things work
+when they come back to them months later!
+
+#### Collaborative brainstorming
+
+When trying to solve problems, it's always a good idea to brainstorm with teammates and backboard ideas off of them. Not only does this
+give the whole team a sense of ownership over each problem which has been solved in the course of working on the project, but also helps
+teammates understand a solution before it is even implemented. This will also make reveiwing contributions easier for teammates, and makes
+it more likely that teammates will find the solution agreeable when it is time for them to review it.
+
+## Becoming a non-technical contributor
+
+#### In a nutshell
+
+Writing the code is one small part of gaining success as an open source project. Most of the work done on a project is actually non-technical.
+This section includes some examples of non-technical work which every project needs done in order to succeed.
+
+#### Managing task definition, assignment, and progress
+
+I.e.,, project management. A successful project will have a good road map, and a good road map will consist of tasks. Every project needs
+someone who can help make sure tasks are getting the attention they need, make sure it is known by everyone who is working on a given task,
+and check in with teammates on how tasks are progressing to ensure the status of a task in the issue tracker reflects reality.
+
+#### Managing project needs/resources
+
+Another project management need, every project needs someone who can help make sure that there is enough expertise and help on the team
+to accomplish the tasks which need to be accomplished by the deadline which they need to be completed by.
+
+#### Facilitating discussion
+
+Sometimes getting the conversation is the hardest part of collaborating. Every project needs someone who is willing to jump in head first
+and kick start a discussion between collaborators when they seem all to willing to remain quiet.
+
+#### Maintaining focus on the mission
+
+Technically minded contributors can often times become distracted by minutiae, such as what software library to use to solve a specific problem
+or whether the code base should be written out using tabs or spaces. It is extremely helpful for every project to have someone who can interject
+when these nitpicky conversations go on too long or dominate the discourse too much to remind the team of the end goal of the project, and remind
+them that the success or failure or the project's mission almost certainly does not rely on the outcome of these debates.
+
+#### Evangilism
+
+A project is only as helpful as the number of people it can reach. Every successful project needs contributors who can help spread the word about
+the project, and can help get it into the hands of the people who will find it the most useful.
+
+#### Opening up feedback channels for users
+
+Just as a project is only as good ad the number of people it can reach, it is also only as good as the ability of its users to wield it. Every
+successful project needs people who are reaching out to and talking to users to determine how helpful or useful the project is in its current
+state, and gathering feedback on how it could be more useful or helpful.

starting-a-project.md

@@ -0,0 +1,123 @@
+## Roadmapping
+
+#### In a nutshell 
+
+Roadmapping is the process of establishing one or more concrete, achievable goals and
+laying out each of the tasks which must be completed in order to accomplish each goal.
+To have a useful roadmap, it is important that these goals and the tasks which need to
+be done to accomplish them are explicitly documented, and easily accessed by all members of the team.
+
+It is important that the tasks which compose a goal in a roadmap be tracked; It should be
+known at all times whether or not a task is completed, if it's actively being worked on,
+and who is working on it if it is.
+
+Examples of good roadmap goals:
+
+- Implement a MVP
+- Implement all API endpoints
+- Complete 5 user tests
+
+Roadmap goals to avoid:
+
+- Complete the project
+- Find users for user testing
+
+#### Why Bother
+
+Like any other activity which demands time and effort from the team members of a project, it is important
+to understand the value prospect of roadmapping. This section describes some of the important and tangible benefits of roadmapping a project.
+
+###### Make work distributable
+
+When a goal is broken down into a step-by-step process which is accessible to the entire team,
+then each team member can take on a step, allowing multiple steps to be worked on by different
+people at the same time.
+
+###### Make onboarding simpler
+
+When the current project goal and the tasks is consists of are documented, it becomes simpler to 
+take on new contributors. New contributors can simply be pointed to the location in which all of
+this information is documented, and select a task to begin working on. This simplicity lowers
+the barrier of entry for people to get involved with a new project.
+
+###### Make project progress trackable/measurable
+
+Documenting the tasks which need to be accomplished to fulfill the current project goal is the
+first step toward having a process for documenting the in-progress and completion status of each
+such task as well. This allows for a concrete measurement of progress toward a goal; how many tasks
+are done vs how many are not can help quantify how close the team is to accomplishing the overall goal.
+
+###### Make collaboration easier
+
+When individual tasks are being tracked as part of a roadmap, this makes it easier for teammates to
+collaborate. Teammates can avoid duplicating effort by knowing who is working on what, and have a shared
+understanding of what needs to be worked on next.
+
+## Onboarding
+
+#### In a nutshell
+
+Onboarding is the process of taking a potential new contributor from the point of knowing nothing about
+your project up to the point of making impactful contributions. As an open source project to which people
+donate their time, it is important to set reasonable expectations around contributors; many will come and
+go over the lifetime of a project. Because of this reality, it is important to keep the barrier of entry
+to new contributors as low as possible.
+
+#### Doing it successfully
+
+###### Simple introspection into current project status and tasks
+
+It is important that a new contributor can easily view the current project status, and determine from
+the current status of the project which tasks need to be done but are not currently being worked on.
+This provides a direct path for a new contributor to know how to become immediately helpful to a project.
+This is a need which can be met by establishing and maintaining a project roadmap, with tracked tasks.
+
+###### Clear, concise, up-to-date instructions on getting started with development (on all platforms!)
+
+All projects should provide instructions on how developers can setup their local machines to start
+working on the project. It is important that instructions exist **for every major platform** (Windows, OS X, Linux); 
+every individual has their own preferences, and excluding platforms which your current team does not
+prefer alienates potential contributors. This should be done on a best effort basis; if no one
+on the team has access to a Windows license or to a Mac Book in order to provide instructions, then
+it simply cannot be done.
+
+What's perhaps most important about this point is that projects should avoid incorportating platform
+specific workflows into the development process (e.g., requiring batch scripts or AppleScript as part
+of the development process).
+
+###### Documented code base
+
+The code base should have comments on all methods and functions, and before any sequences of difficult
+to read or unusual code. This is a general coding best practice, but is highlighted in this context
+because of its impact on the ability of a new contributor to quickly become familiar with the current
+code base (and therefore more quickly make meaningful contributions)
+
+###### Human contact!
+
+Always be available to potential new contributors to ask questions, or even proactively reach out to
+them to try to help them find tasks to work on! The best documentation in the world is still no
+substitute for old fashioned human contact and communication. Contributors usually join projects
+to feel like they're working with a group of people to accomplish something.
+
+## Keeping up momentum
+
+#### In a nutshell
+
+Keeping a project moving forward is important; having a sense of progress keeps team members invested
+and gives the project the best chance of actually launching. This section covers some tips on helping
+to continuously foster a sense of progress in a project.
+
+#### Regular check-ins
+
+Have team members regularly report the current status of tasks they are working on. Not only does this
+help each team member motivate themselves to have progress to show, but it also gives the team insight
+into when a team member may need help with a task, or no longer has time to continue working on a task.
+This transparency also helps ensure that task and project statuses remained up to date, and reflect the
+actual state of the project. In addition to helping foster a sense of ongoing progress, this helps with
+things like new contributor onboarding and roadmap tracking as well.
+
+#### Goals and Deadlines
+
+When establishing roadmaps, set target dates for each step in the roadmap. Constraining goals to
+be accomplished by a certain deadline helps set a pace for progress on the project, and can provide
+that sense that the project is continuing to move stadily forwad.