Publish activitysim online training materials based on agency partners’ needs

[jpn--]

@ActivitySim/product, please describe what you would like this to be?

• TikTok style videos introducing features?
• Longer tutorial videos? e.g. SimWrapper OMX Viewer
• Live online classes offered periodically / archived for offline viewing later?
• Walkthrough notebooks similar to a textbook chapter? e.g. Estimating Parameters

[bhargavasana]

Here are some ideas proposed by MTC, Met Council, and SEMCOG. Once we gather more input from other members, we can split this into multiple issues.

Documentation Improvements:

• Troubleshooting and FAQs:

  • Add a section for common problems, fixes, and troubleshooting.
  • Include screenshots of common errors and crashes with descriptions of solutions.

• Inputs and Outputs Documentation:

  • Provide clear documentation on data inputs and outputs (consider agency-specific variations).

• Summaries & Standardization:

  • Clarify how to run summaries, especially if there’s any standardization or guidance.

• Documentation on Submodels:

  • Add more detailed documentation on submodels, including:
    • Data inputs
    • Configuration options
    • Data outputs

• "Ask a Friend" Feature:

  • Implement a button or feature that allows users to contact other MPO partners with relevant expertise.
  • Could include a roster of project knowledge specialties for partners.

• Data Dictionary:

  • Expand the "Anatomy of a Model" section to include descriptions of fields within each table.
  • Consider creating a separate data dictionary document if it makes the user guide too lengthy.

• Sharrow Documentation:

  • Clarify when to recompile in the "Using Sharrow" section.
  • Document whether the created Sharrow cache can be transferred.

Training and Long-Term Support:

• Training Material Development:

  • Acknowledge that training is an ongoing project, with needs evolving as agencies implement the model.
  • Develop a system for agencies to submit training ideas as they identify gaps in documentation.
  • Periodically review and prioritize training topics (possibly during project phases).
  • Encourage agencies to contribute to developing training materials based on internal expertise.

• Training Formats:

  • Consider creating video tutorials for step-by-step processes like "how to install" and "how to run".

• Simplified Instructions for Beginners:

  • Provide easy-to-understand, step-by-step instructions targeted at entry-level or medium-level agency users.

[joecastiglione]

These were some ideas floated in the 2025-09-23 Product/Community Team meeting

Documentation Strategy and Priorities

Current State Assessment

Jeff Newman's Analysis:

• Current documentation "lousy in absolute terms" but "decent compared to similar tools"
• Industry-wide tendency to skimp on high-quality documentation
• Need for both comprehensive API documentation and practical walkthroughs

Identified Documentation Needs

Multi-Level Documentation Requirements (Feng Xie):

• Basic explanatory documentation for stakeholders unfamiliar with activity-based modeling
• Advanced technical documentation for model developers
• Model calibration and estimation guidance

Project-Level Application Guidance (Ray Ngo):

• Gap in project-level planning documentation (not unique to ActivitySim)
• Need for step-by-step guides for specific planning applications
• Examples: transit subsidies, AV scenarios, telecommuting analysis
• Guidance for local agencies and consulting firms new to ActivitySim

Specific Use Cases Identified:

• Large-scale land use change evaluation (John Gliebe)
• Population Sim and Repop application guidance
• Corridor studies and small area analysis
• Transit product testing and evaluation (TransLink interest)

Documentation Enhancement Proposals

"Cookbook" Approach:

• Jupyter notebook-style walkthroughs similar to OpenAI documentation
• Step-by-step scenario implementation guides
• Balance between toy models and realistic complexity
• 500-600 zone example models for meaningful analysis

Challenges and Considerations:

• Resource requirements for comprehensive documentation development
• Need for validated, realistic example scenarios
• Balance between software mechanics and modeling interpretation
• Boundary definition: tool usage vs. general modeling education

Technical Implementation Considerations:

• Model size optimization for training purposes (3-minute runtime target)
• Example validation and quality assurance
• Integration with existing estimation mode examples
• Consistency between model specification and available data

Regional Variability Concerns

• Response expectations vary significantly by region (e.g., Vancouver vs. average US transit mode share)
• Documentation should focus on setup methodology rather than prescriptive response values
• Need for guidance on reasonableness checking without region-specific benchmarks