> Source URL: /demos/cs1-path/course.style-guide
---
course: CS1
version: 1.0
---

# Content Style Guide

This guide defines conventions for all curriculum materials in this repository. Both human authors and AI agents should follow these guidelines.

## Voice & Tone

- **Approachable**: Write as if explaining to a curious friend, not lecturing
- **Encouraging**: Acknowledge that programming is challenging; normalize struggle
- **Direct**: Get to the point; students appreciate clarity over verbosity
- **Inclusive**: Use examples that resonate with diverse backgrounds

## Writing Conventions

### Instructions

- Use second person ("you will create...")
- Number steps for sequential tasks
- Use bullet points for non-sequential items
- Keep paragraphs short (3-4 sentences max)

### Code Examples

- Always include comments explaining non-obvious lines
- Show expected output when helpful
- Use meaningful variable names (not `x`, `temp`, `foo`)
- Keep examples focused—demonstrate one concept at a time

### Technical Terms

- Define jargon on first use
- Link to relevant lecture materials when referencing concepts
- Use consistent terminology throughout (e.g., always "function" not sometimes "method")

## Code Style (Python)

```python
# Use snake_case for variables and functions
user_name = "Alice"
def calculate_average(numbers):
    pass

# Use descriptive names
# Good:
total_score = 0
# Avoid:
ts = 0

# Include docstrings for functions
def greet(name):
    """Print a greeting message for the given name."""
    print(f"Hello, {name}!")
```

## What to Avoid

- **Don't let themes overshadow learning**: If using themed content, the programming concept must remain central
- **Don't assume prior knowledge**: This is CS1—explain everything
- **Don't show solutions too early**: Guide students toward discovery
- **Don't use overly complex examples**: One concept per example
- **Don't use idioms beginners won't understand**: Avoid list comprehensions, lambda, etc. until taught

## File Conventions

### Naming

All content files use type-hinted names: `{name}.{type}.md`

| Type                   | Purpose                              | Example                              |
| ---------------------- | ------------------------------------ | ------------------------------------ |
| `.outcomes.md`         | Learning outcomes                    | `course.outcomes.md`                 |
| `.syllabus.md`         | Course syllabus                      | `course.syllabus.md`                 |
| `.schedule.md`         | Timeline/calendar                    | `course.schedule.md`                 |
| `.slides.md`           | Lecture content                      | `lecture-01.slides.md`               |
| `.spec.md`             | Assignment specification             | `lab-01.spec.md`                     |
| `.rubric.md`           | Grading criteria                     | `project-1.rubric.md`                |
| `.persona.md`          | Student profile                      | `student-ax7k.persona.md`            |
| `.feedback-harness.md` | Feedback context (reviewer artifact) | `ax7k-project-1.feedback-harness.md` |
| `.feedback.md`         | Student-facing feedback              | `ax7k-project-1.feedback.md`         |
| `.guide.md`            | How-to guide                         | `setup.guide.md`                     |
| `.template.md`         | Reusable template                    | `template.lab.md`                    |

### Frontmatter

All content files include YAML frontmatter with relevant metadata.

### Links

Use relative markdown links to connect related files. This enables:

- Agent navigation through the curriculum
- Consistent cross-references
- Knowledge graph visualization

### Feedback Files

There are two types of feedback files with distinct purposes:

- **`.feedback-harness.md`** (in `curriculum/feedback/`): Reviewer artifact that bundles all context needed for AI and human reviewers to evaluate student work. Contains student profile, project spec, rubric, code snapshot, commit history, and agent instructions. Typically created via custom GitHub Classroom integration.

- **`.feedback.md`** (in `curriculum/students/`): Student-facing feedback file containing only the feedback content delivered to students. Omits internal context (rubric scores, commit history, agent instructions) and focuses on actionable, encouraging feedback.

**Workflow**: Feedback harness → generate feedback → extract to student-facing `.feedback.md` file in `students/` folder.

## Personalization Guidelines

When generating personalized content:

1. Reference the student's [persona file](students/) for context
2. Check the [Cohort Profile](cohort/cohort.profile.md) for class-wide themes
3. Maintain alignment with the [Course Outcomes](course.outcomes.md)
4. Keep the learning objective primary; personalization is secondary


---

## Backlinks

The following sources link to this document:

- [Style Guide](/demos/cs1-path/index.path.llm.md)