docs: Add comprehensive documentation hub#11
docs: Add comprehensive documentation hub#11github-actions[bot] wants to merge 1 commit intomainfrom
Conversation
Add Diátaxis-structured documentation with tutorials, how-to guides, reference materials, and explanations to improve repository usability. New documentation includes: - Documentation hub with clear navigation (docs/README.md) - Getting Started tutorial for new users - How-to guide for adding crop records - Farm glossary with 50+ terms - Complete data dictionary with field definitions - Label reference guide - File naming conventions - Seasonal calendar explaining farm operations - Explanation of why GitHub works for farm management Documentation follows: - Diátaxis framework (tutorials/how-to/reference/explanation) - Plain language principles - Progressive disclosure (high-level first) - Accessibility best practices Updated root README to link to new documentation hub. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
github-actions
bot
added
documentation
|
Closing: superseded by #12 which was merged with more comprehensive documentation. |
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive documentation hub following the Diátaxis framework to improve repository usability and onboarding. The documentation is organized into four types: tutorials (learning-oriented), how-to guides (task-oriented), reference materials (information-oriented), and explanations (understanding-oriented). The documentation provides clear guidance for new users, practical task instructions, technical specifications, and contextual understanding of farm operations and repository design.
Changes:
- Created 10 new documentation files organized into a docs/ directory following Diátaxis principles
- Added documentation hub index (docs/README.md) with clear navigation
- Updated root README.md to link to the new documentation hub
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 17 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/README.md | Documentation hub index with navigation to all sections |
| docs/tutorials/getting-started.md | 15-minute beginner tutorial for repository navigation and first issue creation |
| docs/how-to/add-crop-record.md | Step-by-step guide for documenting crop planting/harvest events |
| docs/reference/glossary.md | Comprehensive glossary of 50+ farm and repository terms |
| docs/reference/data-dictionary.md | Complete field definitions and validation rules for all farm data types |
| docs/reference/labels.md | Guide to GitHub labels used in the repository |
| docs/reference/naming-conventions.md | File and directory naming standards |
| docs/explanation/seasonal-calendar.md | Annual cycle of farm operations across all four seasons |
| docs/explanation/why-github.md | Rationale and justification for using GitHub for farm management |
| README.md | Added prominent link to documentation hub for new users |
| ````markdown | ||
| | Field | Crop | Variety | Planting Date | Expected Harvest | | ||
| |-------|------|---------|---------------|------------------| | ||
| | North 40 | Corn | Pioneer P1197 | 2026-05-01 | 2026-10-15 | | ||
| | South Field | Soybeans | Asgrow AG24X9 | 2026-05-15 | 2026-10-20 | | ||
| | East Section | Wheat | WB-Grainfield | 2026-09-20 | 2027-07-10 | | ||
| | **West Field** | **Corn** | **DeKalb DKC62-54** | **2026-05-05** | **2026-10-18** | | ||
| ```` |
There was a problem hiding this comment.
This code fence uses four backticks (````) instead of the standard three (```). This should be changed to maintain consistency with standard Markdown formatting practices.
|
|
||
| ## Related Resources | ||
|
|
||
| - [Farm Operations Overview](./farm-operations.md) — Deeper dive into each operation type |
There was a problem hiding this comment.
This link references a file that doesn't exist in this PR: farm-operations.md. While the PR description mentions this as future work, linking to non-existent files creates broken links. Consider either removing this link or commenting it out until the file is created.
| - [Farm Operations Overview](./farm-operations.md) — Deeper dive into each operation type | |
| - Farm Operations Overview — Deeper dive into each operation type (coming soon) |
| - "Cow limping in south pasture" | ||
| - "Schedule annual sheep vaccinations" | ||
| - "Monitor sick calf" | ||
|
|
There was a problem hiding this comment.
The Type Labels section is missing two labels that exist in .github/labels.yml:
- "field-observation" (color: #558B2F, description: "Field scouting and observations")
- "needs-review" (color: #AB47BC, description: "Ready for review or approval")
These labels should be documented to provide complete reference information for users.
| #### 🌱 field-observation | |
| - **Color:** Green (#558B2F) | |
| - **Use for:** Field scouting and observations in specific fields or paddocks | |
| - **Examples:** | |
| - "Scout North 40 for soybean aphids" | |
| - "Check corn emergence in South Field after heavy rain" | |
| - "Walk alfalfa stand to assess winterkill near creek bottom" | |
| #### ✅ needs-review | |
| - **Color:** Purple (#AB47BC) | |
| - **Use for:** Work that is ready for review or approval by another person | |
| - **Examples:** | |
| - "Review updated feeding plan for dairy barn" | |
| - "Approve revised planting schedule for East Field" | |
| - "Check compliance paperwork before grant submission" |
| **Animal ID Format:** | ||
| - Beef Cattle: BC-### (e.g., BC-001, BC-045) | ||
| - Dairy Cows: DC-## (e.g., DC-01, DC-12) | ||
| - Sheep: SH-## (e.g., SH-01, SH-28) | ||
| - Horses: H-# (e.g., H-1, H-2, H-3) |
There was a problem hiding this comment.
The documented Animal ID format doesn't match the actual format used in livestock/health-records.md:
- Documentation specifies: "BC-###" for beef cattle, "DC-##" for dairy cows, "SH-##" for sheep, "H-#" for horses
- Actual data uses: "C-001" for cattle (no distinction between beef/dairy), "S-001" for sheep, "H-001" for horses
Either the documentation should be updated to reflect the actual format used, or the existing data should be migrated to match the documented format. Consistency is important for data integrity.
| ````markdown | ||
| github4farms-training/ | ||
| ├── crops/ # Everything about what we grow | ||
| ├── livestock/ # Everything about our animals | ||
| ├── equipment/ # Everything about our machinery | ||
| └── compliance/ # Everything about regulations and grants | ||
| ```` |
There was a problem hiding this comment.
This code fence uses four backticks (````) instead of the standard three (```). While this might render correctly in some Markdown parsers, the conventional format for fenced code blocks is three backticks. This should be changed to maintain consistency with standard Markdown formatting practices.
|
|
||
| ## Related Resources | ||
|
|
||
| - [How to Use GitHub Issues Effectively](../how-to/use-github-issues.md) |
There was a problem hiding this comment.
This link references a file that doesn't exist in this PR: use-github-issues.md. While the PR description mentions this as future work, linking to non-existent files creates broken links. Consider either removing this link or commenting it out until the file is created.
| - [How to Use GitHub Issues Effectively](../how-to/use-github-issues.md) | |
| <!-- TODO: Add link when ../how-to/use-github-issues.md is created: | |
| - How to Use GitHub Issues Effectively | |
| --> |
| - [Repository Design](./repository-design.md) — How this repository is organized | ||
| - [Farm Operations Overview](./farm-operations.md) — What we track and why |
There was a problem hiding this comment.
These links in the "See also" section reference files that don't exist in this PR:
repository-design.mdfarm-operations.md
While the PR description mentions these as future work, linking to non-existent files creates broken links. Consider either removing these links or commenting them out until the files are created.
| - [Repository Design](./repository-design.md) — How this repository is organized | |
| - [Farm Operations Overview](./farm-operations.md) — What we track and why | |
| - Repository Design — How this repository is organized | |
| - Farm Operations Overview — What we track and why |
| - [Your First Issue](./tutorials/creating-your-first-issue.md) | ||
| - [Recording Equipment Maintenance](./tutorials/recording-equipment-maintenance.md) | ||
|
|
||
| ### 🔧 [How-To Guides](./how-to/) | ||
| **Task-oriented** — Practical steps to accomplish specific goals | ||
|
|
||
| Use these when you need to complete a specific task or solve a particular problem. | ||
|
|
||
| - [Adding Crop Records](./how-to/add-crop-record.md) | ||
| - [Logging Equipment Maintenance](./how-to/log-equipment-maintenance.md) | ||
| - [Updating Livestock Health Records](./how-to/update-livestock-health.md) | ||
| - [Tracking Compliance Deadlines](./how-to/track-compliance-deadlines.md) | ||
| - [Using GitHub Issues Effectively](./how-to/use-github-issues.md) | ||
|
|
||
| ### 📖 [Reference](./reference/) | ||
| **Information-oriented** — Technical descriptions and specifications | ||
|
|
||
| Consult these for precise details about data formats, fields, and terminology. | ||
|
|
||
| - [Data Dictionary](./reference/data-dictionary.md) | ||
| - [Farm Glossary](./reference/glossary.md) | ||
| - [File Naming Conventions](./reference/naming-conventions.md) | ||
| - [Label Reference](./reference/labels.md) | ||
|
|
||
| ### 💡 [Explanation](./explanation/) | ||
| **Understanding-oriented** — Background, context, and design decisions | ||
|
|
||
| Read these to understand the "why" behind farm operations and repository design. | ||
|
|
||
| - [Farm Operations Overview](./explanation/farm-operations.md) | ||
| - [Seasonal Calendar](./explanation/seasonal-calendar.md) | ||
| - [Repository Design](./explanation/repository-design.md) |
There was a problem hiding this comment.
These links in the documentation hub reference files that don't exist in this PR:
creating-your-first-issue.mdrecording-equipment-maintenance.mdlog-equipment-maintenance.mdupdate-livestock-health.mdtrack-compliance-deadlines.mduse-github-issues.mdfarm-operations.mdrepository-design.md
While the PR description mentions these as future work, linking to non-existent files in the main navigation creates broken links. Consider either: (1) creating placeholder files for critical navigation items, (2) commenting out these links with a note that they're planned, or (3) organizing the hub to clearly separate "Available Now" from "Coming Soon" documentation.
| - **Color:** Light Gray (#EDEDED) | ||
| - **Use for:** Work delayed pending parts delivery | ||
| - **Examples:** | ||
| - "Tractor repair awaiting hydraulic hose" | ||
| - "Planter needs replacement disc blades" | ||
|
|
||
| #### ☁️ waiting-on-weather | ||
| - **Color:** Cyan (#C2E0C6) | ||
| - **Use for:** Field work dependent on weather conditions | ||
| - **Examples:** | ||
| - "Field too wet to plant" | ||
| - "Rain delaying harvest" | ||
| - "Waiting for ground to freeze" | ||
|
|
||
| #### 🏥 waiting-on-vet | ||
| - **Color:** Light Pink (#FFC0CB) | ||
| - **Use for:** Animal care pending veterinary visit | ||
| - **Examples:** | ||
| - "Scheduled vet visit next Tuesday" | ||
| - "Waiting for test results" | ||
| - "Pregnancy check scheduled" |
There was a problem hiding this comment.
The color codes documented here don't match the actual label colors defined in .github/labels.yml:
- waiting-on-parts: documented as #EDEDED, but actual is #FFB300
- waiting-on-weather: documented as #C2E0C6, but actual is #29B6F6
- waiting-on-vet: documented as #FFC0CB, but actual is #EC407A
The documentation should reflect the actual label colors defined in the repository configuration.
| Now that you understand the basics, try these tutorials: | ||
|
|
||
| - [Creating Your First Issue](./creating-your-first-issue.md) — More detailed issue guidance | ||
| - [Recording Equipment Maintenance](./recording-equipment-maintenance.md) — Complete workflow example |
There was a problem hiding this comment.
These links reference tutorial files that don't exist in this PR:
creating-your-first-issue.mdrecording-equipment-maintenance.md
While the PR description mentions these as future work, linking to non-existent files creates broken links that will confuse users. Consider either: (1) creating placeholder files with "Coming soon" content, (2) commenting out these links with a note that they're planned, or (3) removing these links until the files are created.
| Now that you understand the basics, try these tutorials: | |
| - [Creating Your First Issue](./creating-your-first-issue.md) — More detailed issue guidance | |
| - [Recording Equipment Maintenance](./recording-equipment-maintenance.md) — Complete workflow example | |
| Now that you understand the basics, try these tutorials (coming soon): | |
| - Creating Your First Issue — More detailed issue guidance (coming soon) | |
| - Recording Equipment Maintenance — Complete workflow example (coming soon) |
Summary
This PR adds a comprehensive documentation hub following the Diátaxis framework to improve repository usability and onboarding for new users.
What's New
Documentation Structure (Diátaxis Framework)
Created
docs/directory organized into four documentation types:📚 Tutorials (Learning-oriented)
docs/tutorials/getting-started.md) — 15-minute beginner tutorial covering:🔧 How-To Guides (Task-oriented)
docs/how-to/add-crop-record.md) — Step-by-step guide for:📖 Reference (Information-oriented)
Farm Glossary (
docs/reference/glossary.md) — 50+ terms covering:Data Dictionary (
docs/reference/data-dictionary.md) — Complete field definitions for:Label Reference (
docs/reference/labels.md) — Comprehensive label guide:File Naming Conventions (
docs/reference/naming-conventions.md) — Standards for:💡 Explanation (Understanding-oriented)
Seasonal Calendar (
docs/explanation/seasonal-calendar.md) — Complete annual cycle:Why GitHub for Farm Management (
docs/explanation/why-github.md) — Rationale covering:Documentation Hub
Created Documentation Hub (
docs/README.md) with:Root README Update
Updated root
README.mdto link to the new documentation hub with a prominent call-to-action for new users.Documentation Quality
This documentation follows best practices:
Files Changed
New Files (10)
docs/README.md— Documentation hub indexdocs/tutorials/getting-started.md— Beginner tutorialdocs/how-to/add-crop-record.md— Task-oriented guidedocs/reference/glossary.md— Farm terminology referencedocs/reference/data-dictionary.md— Field definitionsdocs/reference/labels.md— Label guidedocs/reference/naming-conventions.md— Naming standardsdocs/explanation/seasonal-calendar.md— Annual operations cycledocs/explanation/why-github.md— GitHub rationaleModified Files (1)
README.md— Added link to documentation hubBenefits
This documentation provides:
Testing
Next Steps (Future PRs)
Additional documentation to consider:
Related Issues
Addresses common pain points:
This documentation treats documentation gaps like failing tests — critical issues that must be addressed to maintain repository quality and usability.