Skip to main content

Project Documentation and Repository

Create GitHub Team 🐙

Why Documentation Matters​

Documentation is a critical part of software projects. Think about it. When you're researching the tools you need for your projects, you're more likely to use the one that has documentation and a community that is actively using it. If you see a project on GitHub with no README file, you're likely to just skip it because you don't even know where to start. Large companies also expect you to document your code so that management can add more team members when necessary, and so that 20 years down the road, they can maintain it. For companies and open-source communities alike, documentation ensures:

  • Team scalability and onboarding
  • Long-term maintainability of the codebase
  • Clear communication of the project’s purpose and functionality

Many modern projects use Docusaurus, an open-source tool by Meta, to build and maintain documentation. Docusaurus allows you to write documentation in simple Markdown files located in the documentation/docs/ directory. If you’re new to Markdown, it’s easy to learn!

Assignment Overview​

Your task is to create project documentation using Docusaurus and host it publicly on GitHub Pages.

Documentation Requirements​

Your documentation should include the following:

  1. Intro Page
  • Name of the project
  • Authors
  • Release date
  • Version number

  1. Table of Contents (Auto-generated by Docusaurus)

  2. Revision History (Based on commit history)

  3. Document Overview

  • Summary of the document’s purpose and contents
  1. Body
  • Detailed content of the documentation
  1. References
  • Any external documents, publications, or resources used
  1. Glossary (if applicable)
  • Define any specialized terms used in the document
  1. Figures and Tables
  • Include captions for all figures and tables
  • Cross-reference figures and tables in the document
tip

Use the provided Figure component to include captions with figures and tables.

Quick Markdown Tutorial​

Markdown is a simple way to format text, and Docusaurus transforms it into a professional-looking website. Here’s an example:

# Heading 1
## Heading 2
### Heading 3
  • Heading 2 (##) appears in the right-hand sidebar as a table of contents.
  • Heading 3 (###) appears as a sub-item under Heading 2.

For advanced Markdown features, visit the Docusaurus tutorial section or Docusaurus Markdown Features.

Setting Up the Project​

Step 1: Join GitHub Classroom​

  1. Click here to join the GitHub Classroom and get the starter project.
  2. Log in to your GitHub account or create one at GitHub.
  3. Select your name and TUmail from the list.
  4. Join your team or create a new one if none exists.

Step 2: Configure the GitHub Build Environment​

One team member must complete this setup:

  1. Generate a Personal Access Token:
  • Go to Settings → Developer Settings → Personal Access Tokens → Generate new token.
  • Select these permissions: repo, workflow, admin:read:org.
  • Set the expiration date to the course’s end.
  • Copy the token (you won’t be able to retrieve it later).
  1. Add the Token to the Repository:
  • Navigate to the repository → Settings → Secrets and Variables → Actions → New Repository Secret.
  • Add the following secrets:
  • TOKEN: Your personal access token.
  • USER: Your GitHub username.
  1. Enable GitHub Actions:
  • Go to the Actions tab → Enable workflows.
  1. Deploy the Documentation Website:
  • Edit the README file → Commit and push the changes to main.
  • GitHub Actions will build and deploy your site.
  1. View Your Website:
  • Navigate to the repository homepage → Look for the “github-pages” environment → Click “View Deployment.”

Step 3: Repository Setup​

  1. Edit the README.md file:
  • Add a project overview at the top.
  1. Lock the main branch:

Submission Instructions​

  • Submit the link to your team’s docusaurus website after all members have joined.
  • Ensure all documentation requirements are complete.

Grading​

  • This is a group assignment.
  • Graded as Complete/Incomplete.
  • Incomplete submissions will be invited for resubmission until all requirements are met.

Need Help?​

For questions or assistance, reach out to your instructor or teaching assistant.