Soft Potato v3+ Documentation Restructuring: Master Implementation Plan

Overview & Core Philosophy

The redesign of the softpotato v3+ documentation moves away from a code-centric, API-first approach and adopts a task-centric, progressive-disclosure architecture. This ensures that electrochemists without a background in programming or numerical simulation can run simulations in minutes without being overwhelmed by software mechanics or solver stability criteria.

Architecture & Tier Breakdown

Tier 1: Getting Started & Zero-Install Playgrounds

  • Objective: Enable new users to run a working simulation instantly without local software installation or command-line friction.
  • Core Components:
    • Embed Google Colab and Jupyter execution badges directly into the landing page for core electrochemical experiments (Cottrell, Cyclic Voltammetry).
    • Provide a lightweight, jargon-free local installation guide utilizing accessible tools like Anaconda Navigator or standard pip environments.
    • Establish direct navigation links guiding users from playground environments into task-oriented tutorials.

Tier 2: Task-Oriented Tutorials (Technique-Driven)

  • Objective: Teach softpotato through familiar electrochemical techniques while completely shielding users from numerical solver complexity.
  • Core Components:
    • Restructure tutorials around physical experiments (e.g., simulating reversible outer-sphere electron transfer) rather than software module names.
    • Provide clean, heavily commented script templates where users only edit clearly marked electrochemical input blocks (e.g., scan rate, electrode area, bulk concentrations, diffusion coefficients).
    • Hide spatial grids (dx), time steps (dt), finite difference loops, and solver algorithms behind sensible default parameters.
    • Include clear visual output expected plots so users can immediately verify their script execution.

Tier 3: Electrochemistry Concept Guides & Parameter Translation

  • Objective: Bridge traditional electrochemical textbook notation with Python variable names and data structures.
  • Core Components:
    • Publish a comprehensive parameter translation table mapping standard symbols (DO, DR, k0, alpha, C*) to Python keywords and units.
    • Write conceptual companion guides explaining how physical parameters translate to boundary conditions and mass transport equations.
    • Integrate visual diagrams showing how 1D spatial domains map onto real physical electrode interfaces.

Tier 4: Numerical Solver & Troubleshooting Hub

  • Objective: Quarantine numerical convergence criteria, grid spacing mechanics, and stability warnings away from introductory tutorials.
  • Core Components:
    • Provide plain-language explanations of numerical concepts using intuitive physical analogies (such as slicing diffusion layers into spatial bins).
    • Implement a symptom-based troubleshooting table for common simulation failures (e.g., oscillating currents, NaN values, jagged CV curves).
    • Document guidelines for configuring expanding grids and non-uniform meshes for high-scan-rate or rotating disk setups.
    • Ensure codebase exceptions output human-readable, actionable electrochemical warnings rather than obscure Python tracebacks.

Tier 5: Full API Reference (Advanced Backstop)

  • Objective: Keep exhaustive class and method signatures out of the path of beginners while remaining readily available for advanced users and developers.
  • Core Components:
    • Relocate the full API reference to a clearly separated section at the bottom of the documentation hierarchy or a dedicated advanced tab.
    • Establish clean navigation separating user-facing simulation helpers from core numerical solver classes.
    • Ensure all internal module docstrings are polished and cross-linked to the relevant concept guides.

Execution Milestones & Task Tracking

  • Phase 1: Foundation & Playgrounds

    • Spin up the Tier 1 Colab notebooks for Cottrell and CV experiments.
    • Draft the zero-install setup guide.

  • Phase 2: Tutorial Decoupling

    • Rewrite Tier 2 technique-driven tutorial templates with isolated parameter blocks.
    • Strip all explicit numerical mesh setup instructions out of beginner-facing guides.

  • Phase 3: Reference & Troubleshooting Integration

    • Construct the Tier 3 parameter translation tables and concept guides.
    • Populate the Tier 4 troubleshooting hub with symptom-action mappings.
    • Restructure the sidebar to relegate Tier 5 API references to an advanced backstop section.