Documentation Guide

Use this top-level guide to explain why the repository is documented, what needs to be recorded, and how those records stay current. The Turing Way treats documentation as part of reproducible research: it helps contributors, reviewers, and your future self understand what was done, why it was done, and how to reuse it.

This page sets the overall documentation approach for the project. Use the documentation/ directory for extended, topic-specific material such as data dictionaries, methods notes, workflow descriptions, or user-facing guides.

Why document?

• Documentation makes research reproducible by describing the data, code, decisions, and environment needed to rerun the work.
• Documentation lowers the barrier for contributors by showing how the repository is organised and where to start.
• Documentation preserves context that would otherwise be lost in meetings, chat threads, or personal memory.
• Documentation supports reuse, citation, and accountability by making methods, licences, and responsibilities visible.

What should be documented?

• The repository itself: a clear README, roadmap, participation guidelines, licences, and citation metadata.
• The research workflow: data sources, collection methods, cleaning steps, analysis decisions, and outputs.
• The computational setup: software versions, dependencies, scripts, naming conventions, and automation.
• The project process: roles, communication channels, review practices, decisions, and progress updates.

How should this repository document work?

1. Keep documentation close to the work in version control so updates travel with code, data, and analysis.
2. Write for specific audiences such as maintainers, contributors, reviewers, and people who want to reuse the project.
3. Start with the minimum useful information, then expand it as the project grows instead of waiting for a final version.
4. Prefer concrete instructions, examples, checklists, and links to scripts over abstract descriptions.
5. Review documentation whenever the workflow, team, or tooling changes.

The pages in project-management/ break this into communication, people, project reporting, and tools. For background, see The Turing Way on Code documentation, Creating Project Repositories, and the Guide for Communication.