ADR Suggestion Unified Documentation Structure for EasyScience-Based Data Analysis Libraries

[AndrewSazonov]

To enhance consistency and usability across EasyScience-based data analysis libraries, I propose standardizing the documentation structure with the following main sections:

• Introduction – Provides an overview of {{project_name}}, including its purpose, licensing, latest release details, and contact information.
• Installation & Setup – Guides users through system requirements, environment configuration, and the installation process.
• User Guide – Covers core concepts, key terminology, workflow steps, and essential parameters for effective use of {{project_name}}.
• Hands-on Tutorials – Offers practical, step-by-step examples demonstrating common workflows and data analysis tasks.
• API Reference – An auto-generated reference detailing the available functions and modules in {{project_name}}.
• Contributing – Outlines contribution guidelines, best practices, and the process for contributing to {{project_name}}.

Reference Implementations

• Example of a freshly generated documentation structure: https://easyscience.github.io/peasy-lib
• Example of documentation adapted for an existing project (EasyDiffraction): https://easyscience.github.io/EasyDiffractionLib

[elindgren]

Things we discussed during the group meeting:

• How parsable/crawlable by tools such as Copilot/ChatGPT is the documentation?
• We probably need a limited theory page with basic definitions and/or central concepts.
• It would be nice to have a Citation tab, including a bibliography where we cite the packages we've used, as well as citation instructions for how to cite Easy-packages. A nice to have would be an autogenerated bibtex-entry with the zenodo-url for the latest published version of the package, as well as instructions for how to cite older versions.

[damskii9992]

Comments/suggestions:

• I do not like to have the pull request process described on the documentation page, it is enough to refer to the GitHub and have it there. It is also worded like contributers may make new releases themselves, bumping version numbers and approving pull requests, which I don't think we should allow. Instead I would refer the contributor to read the ADR's at the organization level and repo level and make sure their pull requests are aligned with these, and if not, possibly open a new ADR suggestion. We could also have a sub-page under Contributing linking to the ADR's like Scipp does? https://scipp.github.io/development/architecture-decision-records.html
• You write that this is only for the libraries, should we not also unify the documentation for the applications? And that then begs the question, should we separate the documentations or have them in a single page? Some explanations/documentation will surely overlap, so I see some benefit in keeping application and library documentation together.
• I would simply name the page "Tutorials" rather than "Hands-on Tutorials", which tutorials are not hands-on?
• I would rename the sub-categories, "Basic Examples" to "Basics", as they are tutorials explaining the basis of the library (not a basic example of how to use the library) and "Additional examples" to "Extra" or "Other", as this sub-category is supposed to contain tutorials that does not fall into any of the other categories.
• Do we test that the tutorials can run in Google Colab? I know some other teams had some issues there, and if we have that link we need to ensure that the tutorials can actually run there.
• I would also propose to have some granularity on the API Reference menu, rather than having everything in 1 page. Since we are to adopt the Job structure across the techniques, the first level of the API Reference menu would even be identical across techniques.
• The "Terminology" page confuses me. The explanation of the used data-format is definitely useful, but should maybe be its own sub-page. The remaining contents of the page is the "Glossary" definition, which is fair enough, this is what I expect on a "Terminology" page, and then the "Dictionaries" which, to me, appears to be more API Reference?
• I would merge the "Getting Started" information into the "Workflow Steps" page, as it is mostly empty and contains information about the workflow steps anyways. Maybe rename it too? It is not really a "workflow" per se when used in the library, as the steps can be done in mostly arbitrary order. Maybe "Defining a project"? I'm open to other names too. Also, i know the sub-sub-pages here are still subject to changes.
• I would also remove the "Running tutorials" section from the "Installation & Setup" page, as it is described in the "Hands-on Tutorials" page anyways and it has nothing to do with installation/setup.
• We might also want a "concepts" page to describe what a Parameter is, etc. Maybe that could go under "User Guide"?
• For citation of different version numbers we could take a page from Scipp and do as they do: https://scipp.github.io/about/about.html#development
• I also think we should have release notes on the documentation page.

[AndrewSazonov]

Below, I’ve addressed all the comments from above. Each comment and its reply are placed in a separate cell to simplify further discussion on them individually, if needed.

[AndrewSazonov]

Comment:
How parsable/crawlable by tools such as Copilot/ChatGPT is the documentation?

Reply:
This needs to be checked. I’m not sure what the appropriate metric would be here. Are there existing tools that can be integrated as a separate CI step to perform such a check and provide some sort of score? If anyone has suggestions or experience with this kind of analysis, I’d like to hear more.

[AndrewSazonov]

Comment:
We probably need a limited theory page with basic definitions and/or central concepts.

Reply:
This sounds like a good idea. Could you clarify what you mean by “basic definitions and/or central concepts”? For example, in the case of diffraction, what would you like to see beyond what is already available on EasyDiffractionLib documentation?

[AndrewSazonov]

If we’re talking specifically about the calculators, I agree with you to some extent. Ideally, all the relevant formulas and concepts should be documented within the external calculators themselves. However, in reality, these libraries are often developed by scientists and tend to lack complete or up-to-date documentation.

In such cases, simply telling the user to "go and search for it" - whether through outdated user manuals or even by digging into the source code - doesn't offer a good user experience.

That said, I agree we won’t be able to cover everything in our documentation. The right balance is probably both technique-specific and calculator-dependent. For some calculators, pointing to external documentation may be enough. For others, especially where the documentation is sparse or missing, we might need to provide some basic explanations or references ourselves to help users understand the parameters and models they are working with.

In addition to that, we could at least offer a structured list of useful links, organized by categories such as:

• Introductory theory (for beginners)
• Calculator-specific manuals and resources (for intermediate users)
• Technical references or papers (for advanced users)

This would allow users of different experience levels to find the information they need without getting overwhelmed, and it would help ensure they aren’t left guessing where to start.

[rozyczko]

I'm just afraid of the creation and maintenance cost of all this, compared to how useful will the users find it. Maybe keeping and showing references to actual implementations makes more sense.
E.g.

For asymmetry we use a four-parameter approach, as defined in Fullprof:
https://www.ill.eu/sites/fullprof/downloads/Docs/FullProf_Manual.pdf
in the `Asymmetry` section

[AndrewSazonov]

I agree that the minimum we need to provide is something along the lines of what you describe - clear references to the actual implementations and their original documentation, where available. If time and resources allow, we can expand this in the future.

That said, your example highlights exactly where we can run into issues. The FullProf manual you mentioned is over 24 years old. While many aspects of the underlying physics remain valid, there have undoubtedly been changes and improvements since then. Additionally, it’s not always the case that the relevant equations or detailed explanations are provided in these manuals—or if they are, they can be hard to find or understand without digging into the source code.

So, I think the amount of additional information we provide will need to be handled on a case-by-case basis, depending on the quality of existing documentation and the time we have available.

[damskii9992]

I think I agree with you Andrew. While I would love it if we could have a documentation where all of our theory is described in succinct detail and in a modern and similar language, I simply do not think we have the resources for this.

So I think we will have to adapt and only provide what is most needed for the places where it is most needed as you suggest, because in some cases we certainly can't expect our users to find the information themselves.

I still think we should have the ultimate goal of providing a good internal theory documentation, but just remember that we might never be able to accomplish it i.e. don't prioritize it where it is not needed.

[AndrewSazonov]

To improve clarity and self-explanation, I have:

• Expanded the User Guide with new subsections: “Concept”, “Data Formats”, and “Parameters”.
• Extended the Analysis section under “Workflow Steps”.

We can add more definitions over time, either:

• Within existing sections, if they are generic enough.
• On dedicated parameter pages, where context-specific definitions and examples fit more naturally.

[AndrewSazonov]

Comment:
It would be nice to have a Citation tab, including a bibliography where we cite the packages we've used, as well as citation instructions for how to cite Easy-packages. A nice to have would be an autogenerated bibtex-entry with the zenodo-url for the latest published version of the package, as well as instructions for how to cite older versions.

Comment:
For citation of different version numbers we could take a page from Scipp and do as they do: https://scipp.github.io/about/about.html#development
Having a describing the how to cite the software is indeed important and I will add a subsection to the Introduction page.

Reply:
This is indeed needed and is planned as a subsection on the Introduction page. Adding a link to Zenodo and a button to download an autogenerated BibTeX entry for the latest published version should be straightforward to implement. Including instructions on how to cite older versions makes sense as well.

[AndrewSazonov]

Added a Citation section under Introduction, including a link to Zenodo with citation formats.

[AndrewSazonov]

Comment:
I do not like to have the pull request process described on the documentation page, it is enough to refer to the GitHub and have it there. It is also worded like contributors may make new releases themselves, bumping version numbers and approving pull requests, which I don't think we should allow. Instead, I would refer the contributor to read the ADRs at the organization level and repo level and make sure their pull requests are aligned with these, and if not, possibly open a new ADR suggestion. We could also have a sub-page under Contributing linking to the ADRs like Scipp does? https://scipp.github.io/development/architecture-decision-records.html

Reply:
Agreed. The current Contributing page is just a placeholder, autogenerated from the generic CONTRIBUTING.md file we use in all projects. We need to decide how much detail to include there.
One approach is to keep it simple and general, focused on welcoming contributions, and providing clear links to important resources:

• The repository’s CONTRIBUTING.md
• Relevant Discussions
• ADRs at both the organization and repository levels

This avoids duplication and keeps everything consistent without extra maintenance effort.
We could also follow Scipp’s example and have a dedicated sub-page under Contributing that links directly to the ADRs. This would give contributors a clear entry point to understand the decision framework and ensure their pull requests align with existing architecture decisions, or know when to propose a new ADR.
So the question is: Do we aim for a minimal Contributing page with links to GitHub, or a more comprehensive, auto-generated one that collects everything in one place?

[henrikjacobsenfys]

At the moment, I think it's likely that anyone who wants to contribute will be in contact with one of us. I therefore vote for simple and general. If we find that we're flooded with contributors, we can work on a more comprehensive page.

[damskii9992]

I think I agree with Henrik here, we can always make a more comprehensive Contributing page once we actually start to have contributors . . .
But maybe keep the notes of what would go into the more comprehensive page for the future when/if we decide to implement it.

[AndrewSazonov]

I’ve removed the separate Contributing page and added a brief note with a link to the GitHub contribution guidelines under the Introduction section.

[AndrewSazonov]

Comment:
You write that this is only for the libraries, should we not also unify the documentation for the applications? And that then begs the question, should we separate the documentations or have them in a single page? Some explanations/documentation will surely overlap, so I see some benefit in keeping application and library documentation together.

Reply:
I see some benefits to combining library and application documentation, particularly where they overlap. However, I think the disadvantages of merging them outweigh the benefits. While the top-level structure and some content can be similar - like Introduction, Installation & Setup, User Guide, and Tutorials - there are many differences. For example, the installation process differs significantly. Combining both would require adding extra levels in the Table of Contents, potentially making the documentation more cluttered and confusing. Users looking for instructions on installing an app might be confused by Python library instructions and vice versa.
Tutorials would also differ, both in structure and content - Jupyter notebooks for libraries versus screenshots for applications. While some examples could overlap, libraries are often more flexible and may expose additional functionality not available in the GUI.
Additionally, maintaining a shared API reference would complicate things - tags would be required to distinguish between app- and library-specific parameters, reducing clarity.
Most users will typically focus on either the app or the library. Directing them to a combined page where half of the content is irrelevant isn't ideal.
Finally, merging both docs into one would likely require moving them out of the app and library repositories into a separate repository. For these reasons, I suggest keeping them separate.

[damskii9992]

This should probably be separated into two discussions I realize:

1. Should we also unify the structure of the app documentations to give a similar look and feel for users?
2. Should we have app and lib documentations together?

You answered n. 2 and I think I agree, but you did not answer n. 1.

Regarding n. 2: It is planned that our users should slowly transition from the app to the libs as they get more advanced or need more advanced features. For that reason I would propose adding an "app" button on the lib documentation, which when clicked takes you to the corresponding page on the app documentation (if it exists) and vice versa.
This is especially useful for tutorials where the user might want to see how the workflow could be done in the app versus the lib.

Also, what do you mean about an API reference for the app? Isn't that a concept that only exists for a lib?

[AndrewSazonov]

1. I fully support the idea of unifying the structure of the application documentation, following the same principles used for the libraries, and keeping them as closely aligned as possible. This consistency will provide users with a familiar look and feel, whether they are using the app or the library. Some sections, such as Introduction, could even share common elements where appropriate.
2. Regarding the API reference - you are right. My point was that this is one of the key differences between the library and application documentation, and it’s one of the reasons why merging them into a single resource may not be practical. For end-users of the application, an API reference wouldn’t be necessary.
3. I also agree that we should make the transition from the application to the library (and vice versa) as smooth as possible for users who choose to explore both. However, I believe most users will likely stick with one approach - either the app or the library - depending on their preferred workflow (GUI vs. scripting/Jupyter notebooks). For this reason, rather than adding a persistent navigation button, I opted for a simpler solution:
   • In the Introduction (the first subsection of the documentation), I clearly explain that EasyDiffraction is available as both a cross-platform desktop application and a Python library.
   • I also include a direct link to the corresponding GUI documentation in that section, making it easy for users to switch to the alternative interface if needed.

[damskii9992]

Regarding point 3:

• Not all users will necessarily land on the introduction page when googling for our documentation, as such they might never know this link exists in the introduction page.
• Even if the user knows the link exists, it still requires multiple clicks to go back and forth, worsening the user experience
• If the user additionally wants to find the same workflow/tutorial on the lib/app documentation, to see how the same work is done there, they would have to find the workflow/tutorial themselves, and judge themselves whether the found tutorial does indeed correspond to the tutorial they came from.
• One of our top-level requirements is to be able to export a python script from the apps, containing the corresponding lib workflow which was done in the app, as such I see many users eventually making the transition from app to lib.

Considering the above points, I really do think adding a button to swap between app and lib in the documentation is greatly beneficial for our users and should be added.

[AndrewSazonov]

1. If a user googles “easydiffraction,” they’ll land on easydiffraction.org, which clearly presents both the application and library options. The top navigation includes a “Docs” button that leads to the documentation section, where links to both the app and library docs are shown side by side. Once a user lands in the library docs, the Introduction section again highlights that the project is available both as a GUI application and a Python library, with cross-links provided. So if a user isn’t aware of the other variant, they likely wouldn’t explore the docs much in the first place.

2. At the moment, it only takes two clicks to switch: one to get to the Introduction page and another to jump to the other documentation. Yes, it could be reduced to one, but as I mentioned earlier, I still believe most users will stick to one approach - either the app or the library - depending on their preferred workflow (GUI vs scripting). That’s why a button at the bottom of the page linking to the other variant seems like the most we need right now.

3. If a user wants to compare the same tutorial across both the app and the library, simply adding a global “switch” button won’t be that helpful. It would only take them to the introduction page, and they’d still need to find the tutorial manually - assuming it even exists in both places. Not all tutorials will have a counterpart. The library is supposed to have more functionality and will include more advanced tutorials, while the app might include usage of GUI-specific settings that don’t apply to the lib.
   So if we want to support tutorial-to-tutorial comparison, the best solution would be to add a dedicated button at the top of each tutorial that exists in both versions, linking directly to its counterpart. That could be added alongside the "Download" and "Open in Colab" buttons we already use in the library docs. It keeps things contextual, avoids confusion, and adds real value for users wanting to make that transition.

[AndrewSazonov]

Added a new footer icon linking to the application documentation to reflect the connection between the two.

[AndrewSazonov]

Comment:
I would simply name the page "Tutorials" rather than "Hands-on Tutorials", which tutorials are not hands-on?

Reply:
Agreed. Let’s simplify and just use "Tutorials".

[AndrewSazonov]

Comment:
I would rename the sub-categories, "Basic Examples" to "Basics", as they are tutorials explaining the basis of the library (not a basic example of how to use the library) and "Additional examples" to "Extra" or "Other", as this sub-category is supposed to contain tutorials that does not fall into any of the other categories.

Reply:
Makes sense. Let’s rename the categories to "Basics" and "Extra".

[AndrewSazonov]

Comment:
Do we test that the tutorials can run in Google Colab? I know some other teams had some issues there, and if we have that link we need to ensure that the tutorials can actually run there.

Reply:
Currently, we don’t have a dedicated CI step to test the tutorials on Colab. For EasyDiffraction, we do have a CI step that runs the tutorials on the GitHub build server to check for errors, and they have worked on Colab as well.
However, adding a dedicated Colab test step to the CI would be a great addition if feasible.
Having Colab support is important, especially for workshops and new users who may not have the experience or time to set up a local environment. My recent experience running workshops showed that even creating a virtual environment can be a challenge for some attendees. Running tutorials online removes these barriers and helps attract users who may not be familiar with Python or programming.
We previously used Binder for this purpose, but startup times were frustratingly slow. Colab has generally worked well for EasyDiffraction, with all dependencies installing in under a minute. The main disadvantage is the requirement for a Google account to use Colab.

[damskii9992]

It appears to be possible by using the official Google colab docker image:
https://stackoverflow.com/questions/77437999/google-colab-environment-container-testing-in-github-action

[AndrewSazonov]

Great, I’ll take a look and see how we can adapt it to our needs.

[AndrewSazonov]

The Colab workflow setup is prepared. Setting up the local runner is still needed.

[AndrewSazonov]

Comment:
I would also propose to have some granularity on the API Reference menu, rather than having everything in 1 page. Since we are to adopt the Job structure across the techniques, the first level of the API Reference menu would even be identical across techniques.

Reply:
More granularity is definitely beneficial. However, implementing it would require creating individual Markdown files for each top-level subsection in the API Reference.
If the code structure changes, we’d have to manually check and update links in those Markdown files. Additionally, if we want to include extra descriptions in the Markdown beyond what’s in the docstrings, we’d need to review them every time docstrings are modified.
I think it’s easier to maintain a system where developers focus on complete and accurate documentation within the code docstrings. This way, the API reference is automatically generated, always in sync, and developers don’t have to manage redundant documentation.
For granularity, we can rely on the Table of Contents on the right-hand side of the API Reference page, which provides a clear structure without splitting it into separate files.

[AndrewSazonov]

I’m not entirely convinced that this is a “need-to-have”, or even a “should-have” requirement. We’ve had discussions about prioritizing intuitive and simple APIs, designed primarily for scientists who may have less software development experience. For more experienced developers, I fully agree that a granular API Reference can be very helpful and could be considered a “need-to-have”.

However, as I’ve mentioned in other posts, I believe many of our users will fall into the former group - scientists who prefer working through a simplified interface that mirrors the GUI workflow. For these users, if we provide a well-structured User Guide and Tutorials, most won’t need to dive into the API Reference in depth. That’s why, in my view, a highly granular API Reference is more of a “nice-to-have”.

That said, I’m open to exploring how Scipp has approached this. However, our current method - using Markdown files alongside a simple config file - was chosen deliberately to make it as straightforward as possible for developers to create and maintain documentation. I believe we should stick with this approach.

If we decide that a more structured API Reference is necessary, we could easily develop a script to automatically generate multiple Markdown files, splitting the single-page API Reference into separate sections - one for each main area of the API. This wouldn’t be difficult to implement. Additionally, there may be options in our documentation tools to control the level of granularity directly through the configuration file.

But, I believe we should avoid a setup where part of the documentation for the API reference section is defined in the code and another part is manually maintained in the documentation directory. This kind of fragmented structure can quickly become difficult to maintain.

The final question remains: Is this additional granularity necessary right now, or can it wait until we have more user feedback and a clearer demand?

[henrikjacobsenfys]

I think we can wait for more user feedback.

[damskii9992]

I do not think this needs user feedback, as the API Reference is not just for our future users use, but also for our own internal use.
I cannot count the number of times I've wished that I could find concise information about our API in our documentation.
A clear and structured API Reference is not only a tool for users, but also for us developers. It is especially useful for new team members, or if other people from DMSC needs to use our software (like we do with Scipp, I use their API Reference constantly).
Also keep in mind that our first users will be expert users that know Python, like our IDS's, for which a good API Reference is a "need-to-have".
We can also factor in our yearly summer school, where students are taught via Jupyter notebooks and learn Python on the first day, they would also need a good and structured API Reference.
All in all, I really don't think there is a point to waiting for feedback, as this is a "need-to-have" for any serious software project.

[AndrewSazonov]

1. I absolutely agree that a clear and structured API Reference is super useful for us as developers. But that’s exactly the point - it's a developer-focused tool. Our user-facing documentation should remain user-oriented: simple, friendly, and not overloaded with developer-level detail. As I’ve mentioned in other posts, many of our users will likely be scientists who prefer working through a simplified interface that mirrors the GUI workflow. For them, a well-organized User Guide and Tutorials will usually be enough. That’s why I think we should consider keeping detailed developer documentation separate from the user documentation. You even mentioned in another discussion that you wouldn’t want the pull request process explained in the main docs - I think this is a perfect example of content that belongs in a separate developer doc, especially useful for onboarding new team members.

2. While IDSs are definitely expert Python users, I don’t think we can assume the same of our initial external users. Many will likely come from scientific backgrounds where scripting is secondary to analysis.

3. For advanced users, summer schools, workshops, etc. a clear and structured API Reference is definitely a benefit. I agree that this is a strong use case we should support.

4. Overall, I’m very much in favor of having a structured API Reference. What I’m against is a setup where part of that reference is defined in the code and part is manually maintained in the documentation directory. That kind of fragmentation is hard to maintain and leads to inconsistencies. I believe the API docs should be fully generated from docstrings in the code, and that keeping those docstrings up to date should be the responsibility of the project maintainer.

With that setup, it should be quite easy - during the documentation site build process - to automatically generate multiple pages, each corresponding to a top-level package element like easydiffraction.project, easydiffraction.analysis, etc. Each of these could become its own page within the API Reference section. Then, instead of having one long single-page reference, we’d have multiple focused pages, just like we do for Tutorials. The navigation would show an expandable “API Reference” section, which would improve usability without increasing the maintenance burden.

[AndrewSazonov]

Top-level modules now each have their own page. Sidebar navigation updated accordingly.

[AndrewSazonov]

Comment:
The "Terminology" page confuses me. The explanation of the used data-format is definitely useful, but should maybe be its own sub-page. The remaining contents of the page is the "Glossary" definition, which is fair enough, this is what I expect on a "Terminology" page, and then the "Dictionaries" which, to me, appears to be more API Reference?

Reply:
I’m not attached to the title "Terminology", and I agree that the data formats section should be moved out. In fact, it would be clearer to rename the subsection "Input/Output data format" to something CIF-specific, as it’s currently focused on explaining what CIF is and how we use CIF dictionaries in EasyDiffraction.
As for the "Dictionaries" section: while it may seem like API Reference, it serves a different purpose. It lists predefined parameter names that users can see and set in the GUI, with tags specifying which experiments they relate to. Clicking a parameter name takes the user to a dedicated page with descriptions of the physics behind the parameter, equations, references, etc. - not details about how to use it in the code.
This concept was inherited from the GUI documentation, where the focus is on user-facing descriptions rather than developer-facing API references. So while it might resemble an API Reference at first glance, it’s meant to be a comprehensive glossary of physical parameters with fixed naming conventions.

[damskii9992]

Okay, yes, that confused me quite a bit. I guess if we properly split the app and lib documentations this would not be as confusing.

The word "dictionary" also confused me because I thought it was meant of as a Python dictionary, rather than a glossary kind of dictionary. Maybe a less confusing name would be appropriate?

Also, in this case I would probably also not name the parameters as _cell.length_c as this is their coded names and not how their appear in the application, instead it should simply be a nested bullet points:

• Cell
• • Length a
• • Length b
• etc.
  And possibly with their icon from the app at the top level of each nest, to better relate the parameter to their place in the app.

[AndrewSazonov]

The term "dictionary" is used following CIF (Crystallographic Information Framework) terminology, as established by the IUCr. There are multiple CIF dictionaries, such as the core CIF dictionary, powder CIF dictionary, magnetic CIF dictionary, etc. (See the references here).

In EasyDiffraction (both in the library and the app) we aim to reuse these established and standardized CIF keywords wherever possible. Our input files for both sample models and experiments are written in CIF format.

For any parameters not defined in existing CIF dictionaries, we add them to our custom extension, which you could think of as an EasyDiffraction CIF dictionary. In the documentation, we list all parameters used in EasyDiffraction, grouped by category. Each parameter is tagged with the dictionary it originates from (e.g., core CIF, magnetic CIF, EasyDiffraction CIF). This structure makes it easier for users to navigate and understand the origin of each parameter. Using a different term than dictionary might cause confusion, especially within a community where the concept of CIF dictionaries is already well established.

Regarding coded names vs. display names:

The _cell.length_c name is the parameter's official identifier in the core CIF dictionary. It is:

• The name used in input files describing the sample model
• The name used internally in the library
• The name displayed in the GUI's Text Mode tab, on both the Sample Model and Summary pages.

In the Basic Controls sidebar of the GUI, we use a simplified, more user-friendly version: the category becomes the group name, and the parameter name is shown without underscores (e.g., Length c or just c instead of _cell.length_c). However, the relationship between the display names and the CIF names is kept clear and consistent.

Additionally, when you right-click on any parameter in the GUI (outside of text mode), a pop-up shows the full CIF parameter name as a hyperlink. This links directly to the relevant page in our documentation, where a description is provided, and from there, to the IUCr site if more detailed information is available. The same hyperlinks are also shown in Jupyter notebooks when calling .show_parameters().

Even for users who primarily use the GUI, they will encounter these full parameter names in various contexts. Showing the connection between the GUI display names and their full CIF names is important. It reinforces our commitment to CIF as the standard format and eliminates the need for users to learn an additional file format or set of keywords.

On adding icons:

I agree that including the icons from the GUI in the documentation is a great idea. It would make it easier for users to relate parameter categories (or groups) between the GUI and the documentation, and improve the overall user experience.

[henrikjacobsenfys]

Perhaps it would make sense to mention the display names in the documentation? I don't have a strong opinion on this, but a GUI user might reasonably look for Atomic displacement and Biso, not realising they have to look up _atom_site.B_iso_or_equiv. I don't know if this is worth the effort, though.

[AndrewSazonov]

That sounds like a good idea! We could include this in the documentation for the App, perhaps in a table format, where one column shows the display (pretty) name of the parameter as it appears in the GUI Basic Controls, and the second column lists the corresponding full CIF name, as shown in the GUI’s Text Mode widget.

This would make it easier for GUI users to cross-reference parameters without needing to know the full CIF identifiers upfront.

[AndrewSazonov]

Reorganised and renamed some sections:

• “Parameters” now includes a table of code/CIF names with links.
• Each parameter has its own short description page with a link to IUCr (if available).
• These can be expanded over time with formulas, examples, etc.

[AndrewSazonov]

Comment:
I would merge the "Getting Started" information into the "Workflow Steps" page, as it is mostly empty and contains information about the workflow steps anyways. Maybe rename it too? It is not really a "workflow" per se when used in the library, as the steps can be done in mostly arbitrary order. Maybe "Defining a project"? I'm open to other names too. Also, I know the sub-sub-pages here are still subject to changes.

Reply:
At the moment, the "Getting Started" page is mostly a placeholder, focusing on how to import the package and related basics. The reason for keeping it separate from "Workflow Steps" is intentional.
We are introducing a defined workflow in our libraries, not just in the GUI. The proposed workflow steps - Project, Sample Model, Experiment, Analysis, Summary - reflect the logical progression of data analysis in our packages.
While Sample Model and Experiment can sometimes be swapped (depending on community or personal preferences), the overall idea is to guide users through a structured process that simplifies their experience.
This approach is inspired by UX best practices, making complex processes easier to follow by breaking them into smaller, manageable steps. Other scientific software may present all options at once, resulting in cluttered interfaces. We aim for clarity and usability.
If we structure the GUI this way, it makes sense to introduce the same concept at the library level, especially for non-expert users. While Python experts can use the libraries however they prefer, our focus should be on making the experience intuitive for scientists who aren’t software developers.

[AndrewSazonov]

"Getting Started" section is extended.

[AndrewSazonov]

Comment:
I would also remove the "Running tutorials" section from the "Installation & Setup" page, as it is described in the "Hands-on Tutorials" page anyways and it has nothing to do with installation/setup.

Reply:
The reason I placed the "Running tutorials" section under "Installation & Setup" is because it relates to the setup process required to run the tutorials. It includes instructions on installing the necessary dependencies to launch them locally.
The idea is that all preparation steps are completed before users start working through the User Guide or Tutorials. Otherwise, the user would follow the "Installation & Setup" instructions, move on to the User Guide, and only later, when starting with tutorials, realize they need to install additional dependencies. That could lead to confusion, especially if we end up duplicating "Installation & Setup" steps on the Tutorials page.
That said, perhaps the section title, "Running tutorials", isn't the best descriptor. We could rename it or narrow the content to focus on how to install and run the Jupyter notebooks locally. It’s also important to mention here that there’s an alternative option to run tutorials online, with no local setup required.

[AndrewSazonov]

Renamed to “How to run tutorials” to clarify its role in setting up the environment. Kept under "Installation & Setup", but removed duplicate info from the "Tutorials" page - now only a reference link remains.

[AndrewSazonov]

Comment:
We might also want a "concepts" page to describe what a Parameter is, etc. Maybe that could go under "User Guide"?

Reply:
Having a "Concepts" page sounds like a good idea. Would you envision it being generic enough that we can reuse it as a template for all projects, or would you prefer to include technique-specific content, beyond just project names, etc.?
A general concepts page could be quite helpful for onboarding users across different EasyScience libraries, but we may also need to extend it where techniques diverge.

[henrikjacobsenfys]

I think we'll need to extend it for the different libraries. I'm unsure what the best way to do it is.

[AndrewSazonov]

Added a “Concept” page to the User Guide, describing the broader data processing workflow (Acquisition → Reduction → Analysis) on example of diffraction, focusing on the analysis step. Also added a “Parameters” page with links to individual parameter definitions.

[AndrewSazonov]

Comment:
I also think we should have release notes on the documentation page.

Reply:
I agree that release notes can be useful at times. That’s why I’ve added a link to the GitHub Releases page in the "Latest release" section of the Introduction page.
From GitHub, users can browse all previous releases and see what’s changed.
However, I’m not convinced that adding a dedicated Release Notes page in the documentation itself is necessary. In practice, how often do we look at release notes for other libraries?
For example, we depend on packages like numpy and scipp, but I rarely, if ever, visit their release notes. Instead, I rely on the documentation to find out about available features and how to use them.
As for applications, release notes often pop up right after an update - but I almost never check them in the online docs.
The only exception I can think of is FullProf, where I’ve had to dig through release notes several times - mostly because their documentation is a 20-year-old PDF that hasn’t been updated. Following features via release notes in that case is a nightmare, and exactly what we should avoid.
In summary, I suggest we keep the link to GitHub Releases for anyone interested but don’t add a dedicated release notes page in the project documentation itself.

[AndrewSazonov]

Based on our discussion, I’ve updated the EasyDiffraction Library documentation. The latest development version is available at https://easyscience.github.io/diffraction-lib/

Let’s proceed with a second round of review. Once the final version is agreed on, I’ll update the documentation template accordingly for use in the other projects.

[damskii9992]

Question, under User Guide/First Steps you write:

• project.analysis.show_all_params() – to display all available parameters for the analysis step.
• project.analysis.show_fittable_params() – to display only the parameters that can be fitted during the analysis.

What exactly is the difference between these? Considering that project.analysis.show_free_params() is meant to show the parameters that are currently free, then I can't see what the difference between these two would be?

[damskii9992]

And while we're on the subject, maybe add instructions for how the user might find the access point for a specific parameter.
Say that the user calls project.analysis.show_all_params(), they get a list of parameters and decide that they want to access one of these to constrain it, set it free or just know where it lives to know what the parameter actually means (there are many parameters named fractional_x coordinate, for example . . .)

So something along the lines of:

project.analysis.show_all_params() list all parameters with their unique_names, these unique_names can be used to query a specific parameters access point using method insert_method_here.

Because finding the specific Parameter under the list from project.analysis.how_to_access_parameters() can be tedious, if not impossible based on the information provided by the methods.

[AndrewSazonov]

Question, under User Guide/First Steps you write:

project.analysis.show_all_params() – to display all available parameters for the analysis step.
project.analysis.show_fittable_params() – to display only the parameters that can be fitted during the analysis.
What exactly is the difference between these? Considering that project.analysis.show_free_params() is meant to show the parameters that are currently free, then I can't see what the difference between these two would be?

• project.analysis.show_all_params()
  Displays all parameters, including both fittable (e.g. b_iso, fract_x) and non-fittable (e.g. adp_type, wyckoff_letter) ones.
  The non-fittable parameters are what we internally call descriptors in EasyScience, but I intentionally avoid using that term in the user interface to keep things clearer—so users simply see fittable vs non-fittable parameters.
• project.analysis.show_fittable_params()
  Displays only the fittable parameters, which is a subset of show_all_params(). This method is added for convenience.
• project.analysis.show_free_params()
  Displays the subset of fittable parameters that are currently marked as free, meaning they are selected to be optimized during the next fitting step. This is a subset of show_fittable_params().

You can find an example of how these methods behave in this tutorial:
https://easyscience.github.io/diffraction-lib/tutorials/basic_single-fit_pd-neut-cwl_LBCO-HRPT/#show-parameters

[AndrewSazonov]

And while we're on the subject, maybe add instructions for how the user might find the access point for a specific parameter.
Say that the user calls project.analysis.show_all_params(), they get a list of parameters and decide that they want to access one of these to constrain it, set it free or just know where it lives to know what the parameter actually means (there are many parameters named fractional_x coordinate, for example . . .)

So something along the lines of:

project.analysis.show_all_params() list all parameters with their unique_names, these unique_names can be used to query a specific parameters access point using method insert_method_here.
Because finding the specific Parameter under the list from project.analysis.how_to_access_parameters() can be tedious, if not impossible based on the information provided by the methods.

I’m not entirely sure what you’re aiming to achieve with the proposed method.

Both project.analysis.how_to_access_parameters() and project.analysis.show_all_params() display the same parameters but in different formats. The first one presents a full set of components of each parameter: data block, category, entry, parameter name, value, and whether it’s fittable. The second shows the corresponding access point (i.e. the full attribute path you would use in code) and the unique CIF ID used for constraints - both of which are derived from the fields in the first table.

If you’re suggesting adding something like get_parameter_access_point(...), you would first need to find the detailed info for this parameter in the first table, and then call this new method to get the access path - which seems to add an extra step. In practice, I’d expect locating the parameter in either table to be about equally complex, so going through an extra method will not simplify the process.

What I think could really help, though, is adding an explanation of how the access path and CIF ID are constructed from the individual elements shown in how_to_access_parameters(). That way, users could confidently build access paths themselves and use the method mainly as a reference or for verification.

[damskii9992]

The problem is locating a specific parameter from the output of project.analysis.show_all_params() in the output provided by project.analysis.how_to_access_parameters().
So that is why I am suggesting some method to make that easier. There are no fields in the outputs of these two methods which coincide, so identifying a specific parameter is hard. You could simply print the unique_name of all parameters in both outputs. That would make it easy to identify a specific one.

[AndrewSazonov]

The methods show_all_params(), show_fittable_params(), and show_free_params() already include four identifying columns: datablock, category, entry, and parameter. These are split into separate columns for better readability, as combining them into a single long identifier would make the table harder to read.

To address your concern and bridge the gap between these methods and how_to_access_parameters(), I’ve now added the same four columns to the output of how_to_access_parameters(). This makes it straightforward to match a specific parameter across all outputs and easily locate its corresponding Python code access path and CIF unique identifier.

This change make the how_to_access_parameters() table wider, but:

• It consolidates all the key ways to reference a parameter, visually connecting the human-readable description with its programmatic access and CIF representation.
• It avoids having to extend the other three tables (show_all_params, show_fittable_params, show_free_params) with additional columns like UID, which are sometimes quite long and would reduce their readability, especially for show_free_params(), which I expect users will rely on most.