Jam 00 - Exercise 5 - Creating Your Project README

--- title: "Jam 00 - Exercise 5 - Creating Your Project README" tags: - 4 🥳 done - jam00 - setup - documentation - markdown ---   # Exercise 5 - Creating Your Project README {%hackmd dJZ5TulxSDKme-3fSY4Lbw %} ## Overview - Exercise 5 A professional software project needs clear documentation. The `README.md` file is the first thing people see when visiting your repository - it's your project's front door! In this exercise, you'll: - Learn Markdown formatting - Create a professional README - Document your repository :::info 🔑 **Why READMEs Matter** - First impression of your project - Essential for team collaboration - Required by most companies - Shows professionalism - Documents project purpose and setup ::: ## Markdown Basics Markdown is a lightweight formatting language used throughout the software industry. You'll use it to: - Document your code - Write technical specs - Create project wikis - Communicate with teams Here's a quick reference of common Markdown syntax: ````markdown # Main Heading ## Subheading - Bullet points - Like this 1. Numbered lists 2. Are easy too **Bold text** and *italic text* [Links](https://example.com) ``` code blocks for technical content ``` ```` ## Required Steps - Create Your README :::warning ⚠️ **Important Note** Note we aren't exactly providing the specific commands and step for this section. You definitely need to learn Git terminology, and the respective commands to carry out the required steps. This will help you build a deeper understanding of Git and version control. ::: 1. **Create the File** - In IntelliJ, create a file named `README.md` in your project's root directory :::info 🔑 **README Location Matters** The `README.md` file belongs in your project's root directory (the top-level folder) because: - It's automatically displayed on your repository's home page - It's the first file visitors look for when exploring a project - Both GitLab and GitHub prioritize root-level READMEs in their interface - Package managers and development tools expect to find it there - It follows a decades-old convention in software development Think of it like the cover page of a book - you want it right at the front where everyone can find it! ::: 2. **Add Required Content** Your README must include: - Course information - Your details - Repository purpose - Honor code statement (more on this later, just create a section for it now) Here's a template you can start with: ```markdown= # CSCI 205 - Software Engineering and Design Bucknell University Spring 2025 ## Course Info - Professor: [Professor Name] - Section: [Your Section] ## Student Info - [Your Name] - [Your Major] - [Expected Graduation Year] ## Repository Information This repository contains my work for CSCI 205 at Bucknell University. ## Honor Code ```  :::info 🔧 **IntelliJ Markdown Tips** - Preview your Markdown by clicking the preview icon in the top right - Split view shows source and preview side-by-side - Use the formatting toolbar for common operations ::: 3. **Commit Your Changes** - Stage your README.md in order to _add_ it to your repository - _Commit_ with a descriptive _message_ - _Push_ to GitLab > 🔍 **Checkpoint**: Verify your README > > - Visit your GitLab repository > - Your README should appear rendered on the main page > - All formatting should display correctly > - No typos or missing information :::success ✅ **Professional Development Tip** While we use GitLab in this course, GitHub is the industry standard for sharing code publicly. Consider: - Creating a GitHub account for personal projects - Moving appropriate work to GitHub (protecting academic integrity) - Jams are course assignments - publishing them would be like posting exam answers online. They must stay private. - Don't worry though! You'll have exciting projects later in the semester that are perfect for your portfolio! - Using it to showcase skills to employers - Including your GitHub URL on your resume Many employers expect to see your GitHub profile during hiring! :::