Description
The current PEcAn documentation (built with bookdown) has poor navigation UX due to blank or nearly-blank parent pages that serve only as containers for subsections. When users navigate to these pages, they see just a title with no useful content, forcing them to immediately click into a subsection.
The issue stems from how bookdown handles the split_by: section setting in index.Rmd. With this setting, every level-1 header (#) becomes a separate html page. Several chapters have:
- level-1 header with minimal/no introductory content
- all meaningful content relegated to level-2 subsections (##)
This creates blank "landing pages" that provide no value and hurt navigation.
these are few examples of such --
Proposed approach: add introductory content to blank pages
for each blank parent page add:
1 ) brief description of what the chapter covers
2 ) table of contents or summary of subsections with links
3 ) quick reference information where applicable
here are the examples of sparse parent pages; these files have proper headings but could benefit from more introductory content --
Tasks
Description
The current PEcAn documentation (built with bookdown) has poor navigation UX due to blank or nearly-blank parent pages that serve only as containers for subsections. When users navigate to these pages, they see just a title with no useful content, forcing them to immediately click into a subsection.
The issue stems from how bookdown handles the split_by: section setting in index.Rmd. With this setting, every level-1 header (#) becomes a separate html page. Several chapters have:
This creates blank "landing pages" that provide no value and hurt navigation.
these are few examples of such --
Proposed approach: add introductory content to blank pages
for each blank parent page add:
1 ) brief description of what the chapter covers
2 ) table of contents or summary of subsections with links
3 ) quick reference information where applicable
here are the examples of sparse parent pages; these files have proper headings but could benefit from more introductory content --
Tasks
02_pecan_standards.Rmdadd introduction explaining PEcAn's data standardization philosophy, link to subsections01_meteorology.Rmdadd introduction explaining what met drivers are, how to choose one, and a summary table linking to each driver12_troubleshooting-pecan.Rmdadd introduction with common troubleshooting approaches, link to specific issues00_topicalpages.Rmd,00_tutorials_demos_workflows.Rmd): These (PART) headers are bookdown conventions for grouping chapters review if additional intro text is needed or if these can be combined with subsequent files00_*.Rmdindex files for similar issues and ensure they provide value as landing pages