devmountain / github-standard

A living guide on how our projects should be structured at DevMountain.

Project Summary

This is where the summary of the project will go. Explain what the student will be doing in order to complete the project. Also explain what the project is.

Live Example

Click Me!

Please provide live examples to projects you create. This provides more advanced students a way to try to complete the project without reading any instructions and other students a resource to look at if they aren't understanding the instructions.

If a live example is provided, put a screenshot of the landing page below the Click Me! link.

Setup

• fork and clone this repository.
• cd into the root of the project.
• Run npm install. ( If necessary )
• Run nodemon OR npm start etc. ( If necessary )

Provide a screenshot of what a terminal should look like on a successful startup OR a screenshot of what the landing page should look like after spinning up a development server. This provides a visual comparison that they setup the project correctly.

Step 1

Summary

This is where the summary of the step will go. Explain what the student will be doing and how it modifies the project if necessary. Try to make steps that only edit one file, even if the step is super small. The saller a step is, the less confusion there will be on the students end. This also helps students feel like they are making good progress, rather than spending up to an hour on one step.

Instructions

This is where the basic instructions will go. Use a bullet list format. If multiple objectives are need to complete a task in the step, use a nested bullet format. Start a bullet item with an action/verb. If the bullet is a sentence, end it with a period.

If you are building an afternoon project, include a Detailed Instructions section for every step. If you are building a mini project, you do not have to include a Detailed Instructions section because an instructor will be able to explain on a more detailed level. Always start your bullet list by explaining what file the student should open if applicable to the project.

• Open path/to/file.
• Do X.
• Do Y:
  • Do this to accomplish Y.
  • Do this to accomplish Y.
  • Use this code to accomplish Y:
    • Code Snippet Title

      /*
        You can put code snippets in bullet lists as well. However make sure the code snippet is on it's own indentation level. Otherwise your bullet list will become double spaced.
      */

• Do Z.

Detailed Instructions

This is where the detailed instructions will go. Break down the bullet list one by one and go into detail on how to complete the item. Use a combination of text/code snippets/pictures to give the most amount of detail possible. Also include why the student is doing the item or how it modifies the project. The more detail the better. Since the Detailed Instructions is hidden by default don't worry about how long this section is. This is not a copy of the instructions section, avoid bullet list format in here.

Solution

path/to/file

/*

Always include a hidden code solution for each step. This can either be the entire file or just the things that changed in the file. If you end up doing a solution that is not the entire file, be sure to specify that to the student to avoid confusion.

*/

Provide a screenshot or a giphy showcasing the functionality / layout change(s). Providing these screenshots / giphies also help break up the text and provide visual checkpoints for the student. In other words, this helps make the project more digestible.

Step 2

Repeat the format of step 1.

Step 3

Repeat the format of step 1.

Black Diamond

Include a couple challenges to push the project farther. This can just be a bulleted list of objectives to hit. You do not have to supply a solution or any instructions for this area. Black diamonds are not required to follow what we've already taught our students.

• Modify the project to do Y.
• Add local storage to the project.
• Build a back end for the front end.

After the Black Diamond section, include the Contributions and Copyright sections, and then include the DevMountain logo at the very bottom.

Contributions

If you see a problem or a typo, please fork, make the necessary changes, and create a pull request so we can review your changes and merge them into the master repo and branch.

Copyright

© DevMountain LLC, 2017. Unauthorized use and/or duplication of this material without express and written permission from DevMountain, LLC is strictly prohibited. Excerpts and links may be used, provided that full and clear credit is given to DevMountain with appropriate and specific direction to the original content.

github-standard's Issues

Please link to a demo for each project

It'd be great if all projects could have at least a visual of the final thing being built (website), and even better if it were a link to a working demo. It might be worth changing the template README to include such a section, like how on https://github.com/DevMountain/react-routing there is an h2 for Live Example.

An example of a project that would be helped by a link to a demo is https://github.com/DevMountain/node-sessions-afternoon.

Recently I wanted a demo of what was supposed to be built for https://apis.devmountain.com/routing/, so Brack built one for me at https://apis.devmountain.com/routing, but that's probably not the standard location for them.