Download nids-style-guide.md — every convention on this page, as a single Markdown file written to be followed literally by a person or an AI coding agent building an assignment repository.

How to use this page

The How to Create a NIDS Assignment guide covers what an assignment is and why it is shaped the way it is, and the content guide covers what each file should contain. This page answers a narrower question: why every assignment repository looks the same from the outside — the same breadcrumb bar, the same README shape, the same task numbering — so a student moving between assignments always finds the same things in the same places.

If you’re actually building a repository, use the download above for the exact filenames, heading order, and markup to follow; this page is the reasoning behind them. Where the two disagree, the download wins — and where either differs from an already-published assignment, they win too. The assignments published to date predate this guide, and several carry drift that is being corrected rather than copied.

The repository pair

Every assignment is two GitHub repositories under the CAIDA organization:

The topic in the name is lowercase with hyphens, and describes the dataset or subject rather than the course or term — nids-dns-ecosystem, nids-bgp-control-plane, nids-itdk — so the name still makes sense once the assignment outlives whichever class first used it.

Conventions in every Markdown file

Breadcrumb navigation

Every file in the public repository carries the same pipe-separated breadcrumb bar, top and bottom, listing every document in the assignment in reading order. It exists so a student who jumps from a task guide straight to the notebook, or back to the dataset page, always sees the whole assignment and where they currently sit in it — the current page is called out with ⮕ rather than linked:

[README](README.md) | [Introduction](Introduction.md) | [Datasets](Datasets.md) | [Spark](Spark.md) | Tasks ⮕ | [Task 1](Task-1-centralization.md) | [Task 2](Task-2-resilience.md) | [Task 3](Task-3-security.md) | [Notebook](nids-dns-ecosystem.ipynb)

Add a document to the assignment, and the bar needs the new entry in every file, not just the ones adjacent to it — otherwise a student navigating from an older page won’t know the new one exists.

The NIDS banner

README.md carries a short banner directly below the breadcrumb, identifying the page as a NIDS assignment before the title itself:

### [Network Infrastructure Data Science (NIDS) Assignment]

---

# Understanding the DNS Ecosystem

Use this exact wording, brackets included. Some earlier assignments say “Module” instead of “Assignment,” or drop the brackets, or skip the banner outright — all three predate the current naming and are being phased out rather than treated as valid variants.

Linking to a resource

When a resource has more than one useful destination — a paper, a webpage, a direct download — bundle them into one bracketed group rather than three separate bullets, so the reader sees at a glance which resource they all belong to:

- **CAIDA AS Customer Cone and Relationships** — an ASN's customer cone and its relationships with other ASNs [ [paper](https://catalog.caida.org/paper/2013_asrank) | [webpage](https://catalog.caida.org/dataset/as_relationships_serial_1) | [download](https://publicdata.caida.org/datasets/as-relationships/serial-1/) ]

Callouts

A blockquote with a bold lead-in marks anything that interrupts the normal reading flow — a mistake the student is likely to make, or an aside that isn’t part of the main argument:

> **Gotcha:** `collect_set` deduplicates, so a domain listing four nameservers from
> one provider counts once, not four times.

**Gotcha:** is for a mistake worth heading off; **Note:** is for everything else.

README.md

The README is a student’s first stop, and its sections run in a fixed order: title and credits, what the assignment teaches, the ordered path through it, then the file listing and a glossary. (A “Running Locally” section slots in only for the rare assignment that ships its own database — see Execution environment below.)

Authors credits everyone who built the assignment, including collaborators outside CAIDA, as a single comma-separated line directly under the title:

# Exploring the Internet Yellow Pages (IYP): A Graph Model of Internet Infrastructure

**GitHub:** https://github.com/CAIDA/nids-iyp

## Authors

Bradley Huffaker, Romain Fontugne, Malte Tashiro

Learning Objectives is a short paragraph, not a bulleted list. It names what the assignment introduces — the dataset, and the tool, practice, or idea that comes with it — and states what the student will be able to do afterward. Name any new tool explicitly: “you will learn Cypher, Neo4j’s graph query language” leaves no doubt that learning the tool is part of the assignment, not incidental scaffolding.

Overview is the ordered path through the assignment — reading, then tasks, then producing and submitting the deliverable — with each step linking to the document or action it names:

- step 1 [read the introduction](Introduction.md)
- step 2 [read dataset overviews](Datasets.md)
- step 3 [review the tasks](Tasks.md)
- step 4 log into NRP's JupyterHub, upload and complete the nids-dns-ecosystem.ipynb
  - complete each task by replacing the `# YOUR CODE HERE` sections
  - answer all questions
- step 5 download your working notebook and replace ⬅ deliverable
- step 6 commit and push to github

Directory Structure

A fenced file tree naming every shipped file with a short comment — including the tool guide, which is easy to forget to list — and every deliverable the student submits flagged with ⬅, so there’s no ambiguity about what actually gets turned in.

Glossary

An alphabetized list of terms and definitions covering every acronym and piece of jargon the assignment uses, so a student never has to go hunting for what an unfamiliar abbreviation means.

Introduction.md

This file opens with what the student should read and already know, before the conceptual background — because both decide what the rest of the file actually has to explain.

Reading lists what to read before starting, one line each, with a parenthetical tag ((paper), (slides), (webpage)) where the format isn’t obvious. Anything genuinely optional goes in its own Optional Reading subsection later in the file, not mixed into the main list.

Prerequisite NIDS Assignments lists earlier assignments the student needs, linked by full GitHub URL, each with a short note on what it supplies. That note is what makes the boundary between assumed and new material legible — and that boundary is exactly what decides whether this assignment owes the student a tool guide. If there are none, say so explicitly rather than omitting the section:

- None — this assignment is self-contained and does not depend on material from other NIDS assignments.

The rest of the file is background, organized under sections named for the concept or task they support. Split it into its own Background.md only once it’s long enough to stand as its own reference — nids-itdk, whose background documents a full database schema, is the one precedent so far.

Datasets.md

One section per dataset: what it is, how to reach it, and its schema. Where a dataset is a queryable database large enough that a naive query will time out, this is also where you cover which columns are indexed and how to write a query that uses them — the difference between a task that finishes in seconds and one that never does.

If the dataset needs credentials, this is where the student learns the flow: copy the example env file, fill in the values the instructor supplied, and place it next to the notebook.

Tool guides

A tool guide is required for every tool the assignment uses that a prerequisite assignment doesn’t already cover — the same “anything not covered by a prerequisite is new material” rule that shapes the rest of the assignment. If a prerequisite already covers the tool, cite it instead of repeating it; if a prerequisite covers it only partly, ship a guide covering just the difference.

Name the file for the tool itself, whatever kind of tool it is — a query language, a processing framework, a library — and number its sections so Tasks.md and the per-task guides can deep-link to a specific technique instead of pointing at the whole file. A guide needs to actually be reachable, which means showing up in three places: the breadcrumb bar, the README’s directory tree, and a numbered step in the Overview positioned before the tasks, since the student needs the tool before the work that uses it.

Delta guides

When a prerequisite already taught the tool but this assignment uses it differently, write only what changed, and say so up front rather than making the student rediscover it. nids-ucsdnt-expanse’s PySpark-Parquet.md is the model:

# PySpark & Parquet Guide: What's Different in This Module

This page assumes you've already completed `nids-dns-ecosystem` and its `Spark.md`
guide — SparkSession setup, filtering/selecting, groupBy/agg, joins, and broadcast
variables all carry over unchanged. It covers only what is genuinely different here:
the input format, running Spark on a single HPC node instead of a cluster, and the
Parquet handoff between this module's scripts.

Naming the prerequisite guide and listing what carries over unchanged is the whole point — it tells the student exactly which knowledge to bring and which to build fresh.

Tasks.md

Tasks.md is the checklist the student actually works through: a short intro naming the notebook, then one section per task, with the questions underneath as GitHub checkboxes. Questions are numbered sequentially across the whole assignment — Q1 through Q18, continuing across task boundaries — rather than per task, because the student’s write-up and the notebook both refer back to that same running number, and a per-task scheme (Q1.a, Q1.b) would make that reference ambiguous.

Task 0 is always the setup task: reaching the execution environment, uploading the notebook, confirming data access. It ends in verification checkboxes rather than questions, since there’s nothing to analyze yet.

Per-task guides

Each task also gets its own guide, giving the student the pieces they need — the technique, the library call, the formula, a worked snippet on a simplified input — without doing the work for them. What a per-task guide must never contain is the assembled answer: the final numbers, or code that could be pasted straight into the notebook to finish the task. That line is what keeps the guide genuinely useful without giving away the assignment; the assembled version belongs only in the private key repository.

Notebooks and deliverables

Most assignments produce a single notebook, named for the repository. Splitting the work across more than one file is worth doing only when it genuinely divides into separate artifacts — a prototype and a full-period analysis really are different things, which is why nids-ucsdnt-expanse ships both, plus a batch script and a Slurm submission file to go with them. Splitting one continuous analysis across two files for its own sake is not a reason. Every deliverable, notebook or not, gets an ⬅ in the directory tree.

Inside the notebook, cells fall into a repeating rhythm that keeps the notebook and Tasks.md in lockstep: a markdown cell heading the step (matching the ### Task N.M heading in Tasks.md), a code cell stubbed # YOUR CODE HERE with hints pointing at the specific call to use, a markdown cell carrying the question with the same bolded label as Tasks.md, and a markdown answer slot for the student to overwrite. Every Q number ends up with exactly one question cell and one answer slot, worded identically in both places — the whole point of the rhythm is that a student, or a grader, never has to guess which question a given cell belongs to. Setup cells — imports, credential loading, session creation — ship complete and runnable, since the task isn’t about them.

Execution environment

Default to NRP’s hosted JupyterHub: the student uploads the notebook, works entirely in the browser, then downloads and pushes the finished version. That choice is what lets an assignment skip local install instructions and dependency files entirely.

The exception is an assignment that provides its own persistent database — the Postgres behind nids-itdk, the Neo4j behind nids-iyp — which the student has to reach over a tunnel from their own machine. That’s the one case that earns a “Running Locally” section in the README, offering both a uv and a pip/venv install path. An assignment whose data is read live from an API, an S3 object store, or a Spark cluster doesn’t qualify for this — that still runs on NRP.

The private answer-key repository

The paired nids-<topic>-key repository carries two things. The first is an executed, answered copy of every public notebook — every stub filled in, every question answered, run top to bottom with no errors and its outputs saved. If it doesn’t run clean, it isn’t finished; that’s what makes it a reference answer rather than just a draft.

The second is everything an instructor needs to stand up the assignment’s data resources before students can start: loader scripts, container and Kubernetes manifests, credential templates, cleanup scripts, and a README.md that walks through them in order for someone who has never set this assignment up before. nids-itdk-key/README.md is the model — it takes an instructor from an empty NRP namespace through deploying Postgres, loading the data, and handing credentials to students. If the assignment reads its data live and needs no preparation, the README.md should say so rather than leaving the question open.

Files that never ship

A handful of things stay out of the public repository, and out of the key repository too where noted: author scratch notes (anything prefixed z-), real filled-in credentials (only the .env.example template ships), large data files (a data/ directory with instructions for populating it, never the data itself), and local environments and caches. None of these are student-facing or reference material, so none of them belong in either repository. The exact list is in the download.