Usage Examples and Running Your Code
You'll learn how to provide clear, runnable examples that help others (and future you) execute your analysis successfully.
Why Usage Examples Matter
Installation instructions tell someone how to set up your project—usage examples show them how to actually use it. Think of it like a recipe: ingredients and prep are important, but you really need the cooking steps. Without concrete examples, users waste hours guessing command syntax, file paths, or expected inputs.
What to Include
Your README should demonstrate the most common workflows:
Basic execution example:
# Run the main analysis pipeline
python src/analyze_data.py --input data/raw/survey.csv --output results/
Show expected inputs and outputs:
# Train model with custom parameters
python src/train_model.py --data data/processed/features.csv --model-type rf --n-estimators 100
# Expected output: saves model to models/random_forest_20240115.pkl
# and prints accuracy metrics to console
Include notebook workflows:
# Launch Jupyter to explore interactively
jupyter notebook notebooks/01_exploratory_analysis.ipynb
# Or run all cells non-interactively
jupyter nbconvert --execute notebooks/02_main_analysis.ipynb
Make It Copy-Pasteable
Users should be able to copy your examples directly into their terminal. Use realistic file paths, show the working directory context, and demonstrate the full command including any required flags or arguments.
Include a quick-start section that gets someone from zero to a working result in under five minutes—this builds confidence and engagement.
Key Takeaway: Clear, copy-pasteable usage examples transform your documentation from theoretical to practical, dramatically reducing the barrier for others to run and verify your reproducible research.