Documentation strategy and structure

This document is a high-level guide for maintainers and core contributors. It defines the structure, audience, and style for the Jupyter Book documentation.

Documentation Structure¶

The jupyterbook.org website is a unified site that aggregates content from multiple sources. This repository (jupyterbook.org) hosts the landing page and community content, while other sections are proxied from external sites via Netlify rewrites. Many top-level folders in our domain are hosted in other repositories, and proxied to jupyterbook.org with Netlify re-write rules.

Here are major sections and where to find them:

• Landing Page (index.md)

  • Audience: Newcomers and all users.

  • Content: The file docs/index.md becomes the jupyterbook.org/ landing page. It should demonstrate the core value proposition of the Jupyter Book tool, and give all the information needed to orient a new user and know where to look for more information. It should be easy to read, simple, and visually attractive.

• User Docs (/stable, /latest)

  • Audience: Users of Jupyter Book.

  • Content: These are hosted in the docs folder of jupyter-book and served via ReadTheDocs. /stable is the latest release, /latest is the main branch.

• Topic-Area Landing Pages (e.g., /stable/authoring, /stable/build)

  • Audience: Users who want an overview of what a section covers.

  • Content: Each topic area should have a landing page that provides the same function as the main landing page, but focused on that topic. The landing page should be simple, visually attractive, and guide users to content organized by Diataxis categories (Tutorials, How-To, Reference, Discussion). These pages live in the jupyter-book docs.

• Contributor Docs (contribute/)

  • Audience: Contributors to Jupyter Book.

  • Content: How to navigate the project’s repositories, know where to make a contribution, project-wide contributing guidelines and styles, and how to set up the project for development.

• Community and Project Docs (community/)

  • Audience: People who want to learn about the project (not use the product).

  • Content: Team compass, organizational structure, and project history.

• Blog (/blog)

  • Audience: Anyone who is interested in keeping up with what Jupyter Book’s community has been doing.

  • Content: Blog posts from team members and contributors. Hosted in a separate repository and proxied here.

• Team Compass (/compass)

  • Audience: The Jupyter Book core team and contributors.

  • Content: Team-wide practices, policy, and high-level information. Hosted at The Jupyter Book Team Compass and proxied here.

Topic Organization¶

Each topic-area (like authoring/ or execution/) should be categorized by the Diataxis framework. You can intermingle different categories of content on the same page, but don’t intermingle them in the same section within a page.

• tutorials: Goal-oriented guides to lead a user through a complete process (e.g., “Build your first book”). These are usually standalone pages, and come first.

• how-to: Short, focused guides to answer a specific question (e.g., “How do I add citations?”). This usually come just after tutorials.

• reference: Technical descriptions and factual information (e.g., “Configuration options”). This usually goes at the bottom of a page or section.

• discussion: Explanations of key concepts and high-level discussions (e.g., “Why we use MyST”). This usually goes at the bottom of a page or section.

Pages are organized in a flat hierarchy within each topic folder, try not to nest them inside sub-folders unless really needed.

When to create topic-area landing pages¶

Create a [topic].md landing page when:

• The topic is a major user journey (authoring, building, execution, etc.)

• The topic has 4+ pages that need organization by Diataxis categories

• Users would benefit from navigation guidance within the topic

Don’t create landing pages for:

• Simple collections of related pages (like community/ with 5 pages)

• Single-page topics

• Sections with a clear linear flow where direct links work better

Example structure¶

Good structure following this guide:

docs/
├── index.md              # Main landing page
├── authoring.md          # Topic landing page
└── authoring/
    ├── mystmd.md         # Tutorial
    ├── create-content.md # How-to
    └── roles-and-directives.md # Reference

How can I tell what type of content I’m adding?¶

Use the Diataxis compass to decide what type of content you’re adding. Here’s the key table they recommend:

Development Workflow¶

Building the documentation¶

The Jupyter Book repository includes a noxfile.py with commands for building and previewing the documentation:

Build static HTML:

nox -s docs

Start live development server:

nox -s docs-live

The live server will automatically rebuild pages as you edit them, making it easy to preview your changes.

Style¶

• Use active and short language instead of passive language (e.g., Get started rather than Getting started)

• Be direct and to-the-point. Avoid overly wordy sections.

• Make documentation scannable. Provide high-information headers and titles.

• Cross-reference heavily. Rather than re-writing content, link back to a section as a source of truth.