Skip to content

Latest commit

 

History

History
77 lines (47 loc) · 4.44 KB

challenge3.md

File metadata and controls

77 lines (47 loc) · 4.44 KB
Raw

Challenge 3: Documenting Your Project 📝

Person typing Source

Documentation isn't limited to just for your school reports; it's a vital step when developing software and working collaboratively as a team. Communicating ideas and decisions effectively is essential when members within the team are working on different aspects of a project.

Popular open source projects often have excellent documentation to help developers use or contribute to them. Some examples of documentation include:

  1. Summary of the project, eg. purpose and target audience
  2. Setup guides to get started working on the project
  3. Instructions for other team members on how to use features developed
  4. Keeping track of architectural decisions made when developing the project
  5. Troubleshooting steps for commonly faced issues
  6. Code documentation in the form of comment blocks
  7. Sharing useful code snippets

In this challenge, you will be documenting implementation details from today's workshop using README.md files and sharing your solutions with Gists.

In GitHub, READMEs are written in Markdown. If you need a recap on the Markdown syntax, please refer to Challenge 1.

Writing READMEs

Adding README files to a GitHub repository can help to communicate with other users information about the project.

When users first view your GitHub repository, the README.md will likely be the first source of information that they will see. GitHub renders and displays the contents of the Markdown file README.md, which typically contains important documentation of the project.

When browsing directories in your repository, GitHub will render any README.md files present by default. You can also create additional Markdown files with .md extension, which GitHub will render if clicked.

To learn more about READMEs, you may visit the GitHub READMEs Documentation.

Challenge 3.1: Document Implementation Details

Document your solution for Challenge 2 in the README.md file located at challenges/challenge3/README.md.

For convenience, the file is located here. Some details that you can consider including:

  1. What does Challenge 2 require and what did you do
  2. How the solution works
  3. Why you chose your solution
  4. Lessons learnt

Sharing Code with Gists

Gists are an easy way to share snippets of code, configurations and data to others for free. The contents of a gist can vary, from a single line of text, a code snippet, the contents of an entire file or even multiple files.

Gists can be set as public or secret. A public gist can be discoverable by anyone and are searchable. On the other hand, a secret gist is not discoverable nor searchable. However, if another user is provided with the URL of the gists, they can view its contents.

Under the hood, gists are Git repositories. However, they do not have all the features of a GitHub repository like the ability to create branches and pull requests. Gists may not be the right solution if you have more complicated sharing use cases, in which case, a "normal" GitHub repositories is preferred.

Challenge 3.2: Use and Share Gists

Create, edit and share a Gist containing solutions to Challenge 2 with a team member. In addition, improve a group member's Gist.

This challenge will involve multiple steps:

  1. Create a gist with the solutions and documentation (can be a text file or Markdown file) to Challenge 2. Ideally, the gist should contain multiple files.
  2. (Optional) Try editing the newly created gist in 2 ways: from the web and locally.
  3. Share your gist with a group member.
  4. Fork a group member's gist and add some content.

Challenge 3.2 Hints

Spoiler warning

GitHub's documentation on gists should help with completing this challenge.

  1. Creating gists
  2. Cloning and forking gists

< Back to Challenge 2 | Conclusion >