Comprehensive documentation improvements #195
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Complete README.md with installation, quick start, and project overview - Add Getting Started guide with prerequisites and authentication - Add API Reference documenting all datasets, functions, and utilities - Add Examples page with practical code snippets for common tasks - Add Data Sources documentation explaining FRS, WAS, LCFS, SPI, ETB - Add Glossary defining technical terms and abbreviations - Enhance intro.md with clearer problem statement and audience - Reorganize TOC into User Guide, Technical Details, and Validation sections These improvements make the documentation more accessible to new users while maintaining the detailed technical content for advanced users. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Rename files to use hyphens for cleaner URLs: * getting_started.md → getting-started.md * api_reference.md → api-reference.md * data_sources.md → data-sources.md - Add Mermaid diagram showing data processing pipeline - Add citations for survey sample sizes with links to UK Data Service - Update all internal links to use hyphenated filenames - Update README.md links to match new structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Collaborator
|
Quite a lot of hallucinations here (e.g. Constituency dataset)... closing as better to start from scratch. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Major documentation overhaul to improve accessibility and usability:
Changes
New Documentation Pages
README.md: Complete project overview with badges, installation, quick start, dataset comparison table, and linksdocs/getting_started.md: Detailed setup guide with prerequisites, authentication, troubleshooting, and performance tipsdocs/api_reference.md: Complete API documentation for FRS_2022_23, ExtendedFRS_2022_23, EnhancedFRS_2022_23, ReweightedFRS_2022_23, utility functions, and imputation modulesdocs/examples.md: Practical examples including policy reform analysis, distributional analysis, regional analysis, and custom calculationsdocs/data_sources.md: Comprehensive information on FRS, WAS, LCFS, SPI, ETB with access instructions and data pipeline diagramdocs/glossary.md: Definitions of surveys, datasets, statistical terms, entities, income concepts, and abbreviationsEnhanced Existing Pages
docs/intro.md: Rewritten with clearer problem statement, solution overview, target audience sections, and quick links tabledocs/myst.yml: Reorganized TOC into logical sections (User Guide, Technical Details, Validation)Improved Structure
New navigation organizes content by user need:
Benefits
For New Users:
For Experienced Users:
For Contributors:
Test plan
myst build --htmlScreenshots
The documentation now has a clear three-part structure visible in the navigation:
Notes
This implements Phase 1 of the documentation improvement plan. Future enhancements could include:
🤖 Generated with Claude Code