# Documentation Page Overhaul v2

Use nested lists to describe how you would like the documenation structured.

## Current nf-core website structure

> [!Note]
> - *Italics* denotes a category with no page

- Home
- Pipelines
- Resources
- *Components*
- Modules
- Subworkflows
- *Configs*
- Shared configs
- Docs (No drop down though)
- *Banner*
- Getting Started
- Adding modules to pipelines
- nf-test: Example assertions
- nf-core/tools: installation
- Usage
- Getting started
- Introduction
- Dependency installation
- Configuration
- Offline
- nf-core terminology
- Troubleshooting
- Overview
- Basics
- Configuration
- Input output
- Early crash
- Stuck on revision
- Crash halfway
- Update does not work
- Unable to acquire lock
- Docker permissions
- Reference genomes
- Contributing
- Pipelines
- Pipeline file structure
- nf-test
- Assertions
- Components
- Ext.args
- Meta map
- Website
- Markdown
- Code editors and styling
- Code formatting
- Editor plugins
- Harshil alignment
- Tutorials
- Use nf-core pipelines
- Config instutional profile
- Adding a pipeline
- Overview
- Creating a pipeline
- Test data
- Move to nf-core org
- First steps
- Next steps
- nf-core components
- Adding modules to pipelines
- writing nf-core components
- Tests and test data
- Writing nf-test test
- Test data
- Gitpod
- Overview
- Git in Gitpod
- Config
- Webdev
- nf-core repo
- Alternatives
- Contributing to nf-core
- Adding your institution
- Contributing to components
- Contributing to pipelines
- Writing training
- External usage
- nf-core configs outside of nf-core
- Nextflow training
- Creating with nf-core
- Nextflow
- Sync
- Overview
- ( TODO: Finish listing out pages )
- nf-core contributing overview
- Guidelines
- Pipelines
- Components
- External use
- Graphic Design
- Checklists
- Review
- Pipeline release
- nf-core tools
- Installation
- Pipeline
- Modules
- Subworkflows
- TUI
- Custom remotes
- Api reference
- Community
- *What's happening*
- Blog
- *Events*
- Bytesize
- Training
- Hackathon
- Talks
- *Programs and groups*
- Special Intrest Groups
- Mentorships
- Contributors
- About
- About nf-core
- Governance
- Marketing
- Code of Conduct
- Publications
- Statistics
- Join nf-core

### Noted issues

- Side menu doesn't scroll when fully expanded

## James: Suggestion

### General guidance:
- no more than 3 levels

### Structure:

- Users
- Getting started
- Running pipelines
- Configuring pipelines
- Troubleshooting pipelines
- Developers
- Tutorials (e.g. contribute first time) [learning]
- Modules
- Configs
- Subworkflows
- Pipelines
- How to run nf-test (dedicated page, or in modules-pipelines?)
- Specifications [information reference]
- Test-data
- Modules
- Subworkflows
- Pipelines
- Configs
- (?)Graphic design
- Checklists [how to]
- Adding new modules
- Reviewing modules
- Adding modules to pipelines
- Adding new subworkflows
- Reviewing subworkflows
- Adding subworkflows to pipelines
- Reviewing pipelines
- Adding pipelines
- Adding to website
- etc.

Outstanding question: how does `tools` docs fit into this?

## Mahesh: Suggestion

I suggest using the technique described https://diataxis.fr/ to restructure the website documentation.

### General propositions

- No more than three levels deep (fourth+ level are page sections).
- Don't differentiate between users and developers in docs. View all as contributors - people do what they feel they can.
- Separate documentation by Tutorials (learner), How-to (experienced), Explaination (learner), Reference (experienced)
- See [Diataxis: complex heirarchies page](https://diataxis.fr/complex-hierarchies/) for example layout.
- Note: Things don't strictly fit consistently into these buckets
- Reference (describe a product - don't explain):
- What is a module
- What is a subworkflow
- nf-core tool commands
- nf-core api
- Explanation (explain why something is the way it is):
- Why do we use a meta map
- Why do we use the Harshil alignment
- Tutorials (pages with a focus on doing/learning):
- write an nf-core module
- write an nf-core subworkflow
- make review a pull request
- How-to (describe directions to a goal - if this, then that):
- structure a module
- structure a subworkflow
- structure an nf-test

### Considerations

- People are generally not familiar with diataxis
- Maintaining the philosophical separation ( likely not practically possible or restructure needs to be that clear )

### Proposed restructure

> [!Note]
> Work in progress

- Home
- News (*updates*)
- Blog/Bytesize/Hackathon/Talks/Training events/Mentorships
- Special Interest Groups
- Publications
- Statistics
- Documentation ( *This diataxis separation is difficult* )
- Tutorials ( exercises )
- Participate in nf-core
- Slack
- Hackathon
- Run your first pipeline
- Configure a pipeline
- Run a pipeline in a closed environment (offline)
- Interpret pipeline errors
- Add to a pipeline
- Write an nf-core pipeline
- Write an nf-core module
- Write an nf-core subworkflow
- Make a test data set
- Make a metro map
- Explanations
- Terminology
- Best practices
- Error codes
- Summaries ( Overviews/Guidelines ) - Do we need a summary if tutorial covers it?
- Participate in nf-core
- Slack
- Hackathon
- Run pipelines
- run
- offline
- configure
- troubleshoot
- References (checklists)
- Module checklist
- Subworkflow checklist
- Pipeline checklist
- Test data checklist
- Graphic design checklist
- Resources ( *get stuff* )
- nf-core tools
- Pipelines
- Modules
- Subworkflows
- Instutional configurations
- Editor plugins
- Graphic design assets
- About (Contributors *- nf-core is the community*)
- Governance
- Code of Conduct / Marketing
- Join