Documentation Guide
Index for project documentation, methods, workflows, and decisions.
This section collects detailed project documentation. Keep the homepage readable and put methods, data dictionaries, workflows, and decisions here or in related documentation pages.
Good documentation lets contributors, reviewers, and future users understand what was done, why it was done, and how to reuse the work.
Minimum Documentation
| Topic | Where to document it |
|---|---|
| Project aim | README.md and index.qmd |
| Data sources | documentation/ or a dedicated data dictionary |
| Data fields | documentation/ or files stored alongside data/ |
| Workflow | documentation/, analysis/, src/, and runnable code |
| People | README.md, CITATION.cff, and project-management/ |
| Decisions | project-management/ or linked issues and pull requests |
| Licenses | README.md, LICENSE-CCBY.md, and LICENSE-AGPL.md |
| Citation | README.md, CITATION.cff, and Zenodo release metadata |
[INSERT OR REMOVE PROJECT-SPECIFIC DOCUMENTATION LINKS.]
Suggested Pages
| Page | Use it for |
|---|---|
documentation/data-dictionary.qmd |
Field names, definitions, units, and values |
documentation/methods.md |
Collection, cleaning, analysis, and limitations |
documentation/reuse.md |
Download, citation, license, and examples |
documentation/workflow.md |
Scripts, order of operations, and checks |
documentation/repositories.md |
Evaluating repository characteristics (Zenodo, OpenAgrar, discipline-specific options) |
Create only the pages your project needs. A short accurate page is better than a long placeholder.
Maintenance Rule
Update documentation in the same pull request as the data, code, or workflow change. For background, see The Turing Way on Code documentation and Creating Project Repositories.