docs: adopt Diátaxis framework for user documentation#32
Conversation
Benchmark ResultsNo benchmarks configured. Add benchmarks to benches/ directory. Full results available in CI artifacts. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #32 +/- ##
=======================================
Coverage 95.83% 95.83%
=======================================
Files 9 9
Lines 6499 6499
=======================================
Hits 6228 6228
Misses 271 271 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Code Coverage ReportOverall Coverage: 0% SummaryFull HTML report available in CI artifacts. |
There was a problem hiding this comment.
Pull request overview
This PR adopts the Diátaxis documentation framework to provide structured learning paths for NSIP users. The repository had comprehensive technical reference documentation but lacked beginner-friendly tutorials and conceptual explanations. This change adds four types of documentation: learning-oriented tutorials, problem-oriented how-to guides, understanding-oriented explanations, and information-oriented reference materials.
Changes:
- Added initial documentation in all four Diátaxis quadrants (tutorials, how-to guides, explanations, reference)
- Reorganized docs/README.md to use Diátaxis framework with clear navigation
- Created ADR-0003 documenting the framework adoption decision
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/README.md | Reorganized documentation index using Diátaxis quadrants with quick start section |
| docs/adr/0003-adopt-diataxis-documentation-framework.md | ADR documenting framework adoption rationale and implementation approach |
| docs/tutorials/GETTING-STARTED.md | 15-minute hands-on tutorial for NSIP API basics |
| docs/how-to/CONFIGURE-CLIENT.md | Guide for customizing HTTP client timeout and retry settings |
| docs/how-to/COMPARE-ANIMALS.md | Guide for comparing genetic traits across multiple animals |
| docs/explanation/EBV-EXPLAINED.md | Conceptual explanation of Estimated Breeding Values |
| docs/reference/ERROR-HANDLING.md | Complete reference for error types and handling patterns |
docs/tutorials/GETTING-STARTED.md
Outdated
| - [Working with EBV Traits](EBV-TRAITS.md) - Filter and rank animals by genetic traits | ||
| - [MCP Integration](MCP-INTEGRATION.md) - Connect AI assistants to NSIP data |
There was a problem hiding this comment.
These tutorial links reference non-existent files. The files EBV-TRAITS.md and MCP-INTEGRATION.md do not exist in the docs/tutorials directory. Consider either creating these files or removing these links from the "Next Steps" section.
| - [Working with EBV Traits](EBV-TRAITS.md) - Filter and rank animals by genetic traits | |
| - [MCP Integration](MCP-INTEGRATION.md) - Connect AI assistants to NSIP data | |
| - Working with EBV Traits — Coming soon: filter and rank animals by genetic traits | |
| - MCP Integration — Coming soon: connect AI assistants to NSIP data |
docs/tutorials/GETTING-STARTED.md
Outdated
| **How-To Guides:** | ||
| - [How to Configure Timeout and Retries](../how-to/CONFIGURE-CLIENT.md) | ||
| - [How to Compare Animals](../how-to/COMPARE-ANIMALS.md) | ||
| - [How to Calculate Inbreeding Coefficient](../how-to/INBREEDING-CHECK.md) |
There was a problem hiding this comment.
This link references a non-existent file. The file INBREEDING-CHECK.md does not exist in the docs/how-to directory. Consider either creating this file or removing the link.
| - [How to Calculate Inbreeding Coefficient](../how-to/INBREEDING-CHECK.md) |
docs/how-to/COMPARE-ANIMALS.md
Outdated
| .with_trait_range("Weight", TraitRangeFilter { | ||
| min: Some(10.0), | ||
| max: Some(50.0), | ||
| }); |
There was a problem hiding this comment.
The TraitRangeFilter structure and method name are incorrect. According to crates/models.rs lines 71-77, TraitRangeFilter has fields min: f64 and max: f64 (not Option types). Additionally, the method is with_trait_ranges (plural) which takes a HashMap, not with_trait_range (singular). The correct usage would be: SearchCriteria::new().with_trait_ranges([("Weight".to_string(), TraitRangeFilter { min: 10.0, max: 50.0 })].into())
| .with_trait_range("Weight", TraitRangeFilter { | |
| min: Some(10.0), | |
| max: Some(50.0), | |
| }); | |
| .with_trait_ranges( | |
| [( | |
| "Weight".to_string(), | |
| TraitRangeFilter { | |
| min: 10.0, | |
| max: 50.0, | |
| }, | |
| )] | |
| .into(), | |
| ); |
docs/how-to/CONFIGURE-CLIENT.md
Outdated
| ## See Also | ||
|
|
||
| - [Error Handling Reference](../reference/ERROR-HANDLING.md) | ||
| - [API Client Architecture](../explanation/CLIENT-ARCHITECTURE.md) |
There was a problem hiding this comment.
This link references a non-existent file. The file CLIENT-ARCHITECTURE.md does not exist in the docs/explanation directory. Consider either creating this file or removing the link.
| - [API Client Architecture](../explanation/CLIENT-ARCHITECTURE.md) | |
| - API Client Architecture (conceptual overview) |
docs/explanation/EBV-EXPLAINED.md
Outdated
| ## Further Reading | ||
|
|
||
| - [How to Compare Animals](../how-to/COMPARE-ANIMALS.md) - Practical comparison techniques | ||
| - [How to Rank Animals](../how-to/RANK-ANIMALS.md) - Multi-trait ranking |
There was a problem hiding this comment.
This link references a non-existent file. The file RANK-ANIMALS.md does not exist in the docs/how-to directory. Consider either creating this file or removing the link.
| - [How to Rank Animals](../how-to/RANK-ANIMALS.md) - Multi-trait ranking | |
| - How to Rank Animals - Multi-trait ranking (coming soon) |
docs/tutorials/GETTING-STARTED.md
Outdated
| // Search for Maternal breed animals (breed_id: 640) | ||
| let criteria = SearchCriteria::new() | ||
| .with_status("CURRENT") | ||
| .with_gender("M"); // Male animals only |
There was a problem hiding this comment.
The gender filter value should be "Male" (full word) instead of "M". According to the SearchCriteria documentation in crates/models.rs line 49, the gender field expects "Male", "Female", or "Both".
| .with_gender("M"); // Male animals only | |
| .with_gender("Male"); // Male animals only |
docs/how-to/COMPARE-ANIMALS.md
Outdated
|
|
||
| // Fetch all profiles concurrently | ||
| let futures = lpn_ids.iter() | ||
| .map(|id| client.search_by_lpn(id)); | ||
|
|
||
| let profiles = futures::future::try_join_all(futures).await?; | ||
|
|
There was a problem hiding this comment.
This code example uses the futures crate which is not a dependency of the nsip project. The example should use tokio's join functionality instead. For example, use tokio::try_join! or iterate and await sequentially.
| // Fetch all profiles concurrently | |
| let futures = lpn_ids.iter() | |
| .map(|id| client.search_by_lpn(id)); | |
| let profiles = futures::future::try_join_all(futures).await?; | |
| // Fetch all profiles (one request per LPN) | |
| let mut profiles = Vec::with_capacity(lpn_ids.len()); | |
| for id in &lpn_ids { | |
| profiles.push(client.search_by_lpn(id).await?); | |
| } |
docs/how-to/COMPARE-ANIMALS.md
Outdated
| - [How to Calculate Inbreeding Coefficient](INBREEDING-CHECK.md) | ||
| - [How to Rank Animals](RANK-ANIMALS.md) | ||
| - [Understanding EBVs](../explanation/EBV-EXPLAINED.md) | ||
| - [MCP Compare Tool Reference](../MCP.md#compare) |
There was a problem hiding this comment.
These links reference non-existent files. The files INBREEDING-CHECK.md and RANK-ANIMALS.md do not exist in the docs/how-to directory. Consider either creating these files or removing these links.
| - [How to Calculate Inbreeding Coefficient](INBREEDING-CHECK.md) | |
| - [How to Rank Animals](RANK-ANIMALS.md) | |
| - [Understanding EBVs](../explanation/EBV-EXPLAINED.md) | |
| - [MCP Compare Tool Reference](../MCP.md#compare) | |
| - [Understanding EBVs](../explanation/EBV-EXPLAINED.md) | |
| - [MCP Compare Tool Reference](../MCP.md#compare) |
docs/explanation/EBV-EXPLAINED.md
Outdated
|
|
||
| ### Multi-Trait Selection | ||
|
|
||
| Use weighted trait scores (see [How to Rank Animals](../how-to/RANK-ANIMALS.md)). |
There was a problem hiding this comment.
This link references a non-existent file. The file RANK-ANIMALS.md does not exist in the docs/how-to directory. Consider either creating this file or removing the link.
docs/how-to/CONFIGURE-CLIENT.md
Outdated
|
|
||
| ````rust | ||
| let client = NsipClient::builder() | ||
| .base_url("http://nsipsearch.nsip.org/api") |
There was a problem hiding this comment.
The example NsipClient::builder().base_url("http://nsipsearch.nsip.org/api") configures the client to talk to the remote NSIP API over plain HTTP instead of HTTPS, exposing all requests and responses to interception and tampering on the network. If users copy this configuration into production code, an on-path attacker could read or modify genetic data and API responses. Update this example to use https:// for remote endpoints (keeping http://localhost only for local testing) so the recommended configuration uses encrypted transport by default.
| .base_url("http://nsipsearch.nsip.org/api") | |
| .base_url("https://nsipsearch.nsip.org/api") |
Add structured learning paths using the Diátaxis framework: Tutorials (learning-oriented): - Getting Started - 15-minute hands-on introduction How-To Guides (problem-oriented): - Configure Client - Timeout and retry customization - Compare Animals - Side-by-side genetic trait comparisons Explanation (understanding-oriented): - Understanding EBVs - Breeding value concepts and usage Reference (information-oriented): - Error Handling - Complete error type reference Updated docs/README.md to organize all documentation by framework quadrants. Added ADR-0003 documenting the framework adoption decision. Addresses documentation gap identified in repository analysis. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Benchmark ResultsNo benchmarks configured. Add benchmarks to benches/ directory. Full results available in CI artifacts. |
a0ae2fc to
06d6299
Compare
Benchmark ResultsNo benchmarks configured. Add benchmarks to benches/ directory. Full results available in CI artifacts. |
Code Coverage ReportOverall Coverage: 0% SummaryFull HTML report available in CI artifacts. |
Tutorials: - FIRST-API-QUERY.md, INTERPRETING-RESULTS.md, MCP-SERVER-SETUP.md How-To Guides: - BATCH-QUERY.md, EXPORT-JSON.md, FILTER-SEARCH-RESULTS.md - SCRIPTING-INTEGRATION.md, USE-MCP-TOOLS.md Explanation: - BREED-GROUPS-AND-TRAITS.md, DATA-TO-DECISIONS.md - GENETIC-EVALUATION.md, NSIP-DATA-MODEL.md Reference: - CLI.md, CONFIGURATION.md, LIBRARY-API.md, MCP-TOOLS.md Content sourced from NSIP.org research with accurate breed groups (USA Hair/Terminal/Maternal/Range), EBV traits, units (lbs for growth, mm for carcass, % for FEC/reproduction), and selection indexes (USA MAT-HAIR, USA Terminal).
- README.md: update index with all 22 Diátaxis documents - EBV-EXPLAINED.md: add MWWT, WFEC, PFEC, SC traits; fix units to lbs; add USA MAT-HAIR/Terminal index details - GETTING-STARTED.md: correct API field names and examples - COMPARE-ANIMALS.md: fix trait names and method signatures - CONFIGURE-CLIENT.md: fix cross-reference links - ERROR-HANDLING.md: expand examples, fix broken links All growth trait units corrected to lbs to match the NSIP Search API (crates/mcp/analytics.rs). Added note explaining LAMBPLAN uses kg internally while NSIP API reports in lbs.
Benchmark ResultsNo benchmarks configured. Add benchmarks to benches/ directory. Full results available in CI artifacts. |
Code Coverage ReportOverall Coverage: 0% SummaryFull HTML report available in CI artifacts. |
- Add YAML frontmatter (status, date) to ADR-0001, ADR-0002, ADR-0003 - Narrow adrscope validation pattern to [0-9]*.md to skip README.md - Fix line-length lint on checkout action comment - Add ADR-0003 to README index
Benchmark ResultsNo benchmarks configured. Add benchmarks to benches/ directory. Full results available in CI artifacts. |
Code Coverage ReportOverall Coverage: 0% SummaryFull HTML report available in CI artifacts. |
Add all required schema fields: title, description, type, category, tags, status, created, updated, author, project, technologies, and audience.
Benchmark ResultsNo benchmarks configured. Add benchmarks to benches/ directory. Full results available in CI artifacts. |
Code Coverage ReportOverall Coverage: 0% SummaryFull HTML report available in CI artifacts. |
Summary
Adopts the Diátaxis documentation framework to add structured learning paths for NSIP users. The repository had excellent technical reference docs but lacked learning materials for newcomers.
Changes
New Documentation Structure
Closes #30
Generated by the Update Docs agentic workflow.