Documentation

Documentation ensures your work is understandable, maintainable, and transferable — especially across multiple quarters and teams.
Good documentation saves time, prevents confusion, and accelerates onboarding for new contributors.

This page outlines the core expectations for documentation within the practicum, including READMEs, wikis, comments, diagrams, and tooling.

---

Writing Strong README Files

View README Guidelines

Every project must have a clear and informative README.

Minimum Requirements

A strong README should include:

1. Project Overview

• What the project is
• What problem it solves

2. Installation Instructions

• Dependencies
• Setup steps
• Required tools

3. How to Run the App

• CLI commands
• Platform-specific notes

4. Contribution Workflow

• Branching expectations
• PR standards
• Coding standards link

5. Testing Instructions

• How to execute tests
• Required test coverage (if applicable)

Highly Recommended Enhancements

• Screenshots / GIFs
• Feature list
• Release notes
• Link to wiki pages

We Encourage Use of AI

AI should be used to:

• Draft initial README structure
• Improve clarity and tone
• Catch missing steps

AI should enhance clarity, not replace understanding.

---

Maintaining Wiki Documentation

View Wiki Documentation Guidelines

Wikis act as the persistent knowledge base for the practicum.

Wiki Should Include:

• Installation/setup guides
• Coding standards
• Troubleshooting instructions
• Architecture notes
• Engineering best practices
• Deployment process

Wiki Maintenance Recommendations

• Update documentation alongside major feature changes
• Remove deprecated sections
• Revise outdated guidance
• Add summaries after team decisions

AI Encouraged For:

• Summarizing discussions into documentation
• Consolidating multiple docs into one clearer page
• Proofreading existing content
• Providing quick markdown and HTML

---

Commenting Code Appropriately

View Code Commenting Standards

Code comments should explain intent and reasoning.

Good Comments Explain:

• Why a decision was made
• Why something is necessary
• Why an exception exists

Not What the Code Already Shows

Good Examples

// required because API occasionally double-fires this callback

// avoiding += here due to rounding issues with floating point math

Bad Examples

// increments x by 1
x++

JS / TS Specific

• TSDoc/JSDoc encouraged for shared utilities

Python Specific

• Triple-quote docstrings for:
  • functions
  • classes
  • modules

AI Encouraged For:

• Drafting documentation comments
• Condensing logic explanations
• Explaining complex functions succinctly

---

Creating Diagrams & Technical Specs

View Diagram & Technical Spec Guidelines

Diagrams communicate complex systems more effectively than text alone.

Types of Diagrams

• System architecture
• Component structure
• API flow charts
• Deployment pipelines
• Data flow diagrams
• UX flow maps

Recommended Tools

• draw.io (strongly recommended)
• Lucidchart
• Excalidraw
• Whimsical
• Figma

draw.io Advantages

• Free
• Browser-based
• Exports to GitHub markdown
• Integrates with Google Drive
• Diagram templates included

Best Practices

• Use descriptive labels
• Avoid clutter
• Update diagrams following major changes
• Version-control diagrams when possible

Technical Specs Should Include:

• Purpose
• Context
• Key decisions
• Dependencies
• Risks
• Alternatives considered

AI Encouraged For:

• Draft spec writing
• Summarizing architecture discussions
• Drafting system overview documents

---