Usability: Changes to the documentation

[GeigerJ2]

Events

• 2025-09-XX: Meeting with interested people on aiida-qe doc (organized by @mbercx), @Minotakm, @t-reents, @npaulish, @superstar54 (anyone else?).

  Discussion points

  • Provide scaffolding of the documentation
  • 1 example of how a workflow should be documented
  • Xing suggests enforcing docs must be provided together with new workflow in PR
  • Plan for documentation days

• 2025-09-17: Meeting on aiida-core docs and website @GeigerJ2 and @khsrali (@edan-bainglass on holiday, but will respond in text form)

  Discussion points

  • How to proceed with aiida-website
  • Put content from aiida-core RTD on website
  • Transfer aiida-tutorials back to main aiida documentation (now on website) and modify, under category "real-world examples"
  • What to do about arithmetic add? Remove?
  • Simplify / change basic tutorial
    • Getting started in aiida docs -> Beyond basic tutorial, but still short. Main things for running workflows, e.g., Computer / Code yaml files
    • CalcJob schema overview somewhere -> aiida-core?

• 2025-XX-XX: aiida-qe coding days (organized by @mbercx), @Minotakm, @t-reents, @npaulish, @superstar54 (anyone else?)

PRs

• 👌 PwBaseWorkChain: Improve handling of SCF convergence issues aiida-quantumespresso#987
• 📚 Add basic PwBaseWorkChain documentation aiida-quantumespresso#1074

Notes

• Documentation meta-issue: 📚 Discussion regarding documentation.
• PRs by MBx -> Overall structure needs to be agreed upon, then all workflows to be made
  * [# 1074] 📚 Add basic PwBaseWorkChain documentation (rendered here)
  * [# 934] 📚 Docs: Add first version of PwRelaxWorkChain how to (rendered here)
• General notes for documentation:
  • run vs submit, which one to show? 📚 Using engine.run vs engine.submit in documentation aiida-quantumespresso#1127
  • First, quick way how to run something. Then, longer way / advanced section for (what do you need to do to run real stuff: remote computer, submit...). One central place for this.
  • Quick overview for setting up Computer / Code early on in the documentation. Three schemas, for a Computer setup, config, and code setup
  • Highlight YAML way as default over interactive?
• No examples that use PwCalculation directly (at least in "Get Started"), as no protocols available. Then, more advanced section, shows to set up a calculation from a CalcJob.
• More real-world stories
  • Tutorials / How-To's are too general. No real-world scientific use case
  • Example: https://atomistic-cookbook.org/ (Michele Ceriotti group - recipe of the day)
  • Could publish as blog posts, but possibly too long and infrequent?
  • Knowledge gets transfered from person to person through hear-say, better to have it written also in real-world stories.

[khsrali]

For the website, we could consider:
https://astro.build/
https://docusaurus.io/
https://nextra.site/
https://gitbook.com/
https://www.mintlify.com/

[GeigerJ2]

Notes

• Rework "Basic Tutorial"
• Remove auto-generated API reference
• Integrate content from aiida-tutorials into Examples section (materials science examples, aiida-shell example (e.g., what we did for euroscipy)), and drop additional tutorials link (remove old results from Google, eventually archive repo) (both, 1 week focused effort) (to be discussed)
• Meta package, that could test the versioning compatibility
• Entire outline on the left, like here, claude, e.g. https://graphql.org/learn/ or https://docs.claude.com/en/docs/intro @khsrali
• Static linking to docs from webpage (not changing domain name from aiida.net to rtd when clicking on "Docs" button (aiida.net/docs)) @GeigerJ2
• Merge "HowTo" with "Topics", drop HowTo, integrate non-fitting sections elsewhere (both, 1-2 weeks focused effort)
• Change front page (drop events, compare to pyiron; no change of full tech stack)

more scrambled notes from our meeting on 2025-10-03 (ping @khsrali)

• why both usage inside topics and the How-Tos (common in technical documentation)
• get docs background from the people
• set priorities for tasks in Usability: Changes to the documentation #27:
• basic tutorial, what should be about
• aiida-shell, even before calcjob
• use example from euroscipy for general tutorial (better than arithmetic add)
• start with simplest, sequence of logical steps, gradually adding features
• section about demonstrators (these are the three real-world workflows); sirocco example once released would also be very good
• there might be users who just want to have a demo (add online deployments, currently, this still requires the computer/code setup)
• drop auto-generated api from docs and work on meta-package
• simple, general example: script that allows generating a database and that is useful for querying