---
# System prepended metadata

title: Documentation Page Overhaul v2
tags: [drafts, documentation]

---

# 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