Improve docs accessibility #676

Hrovatin · 2025-10-23T14:40:32Z

This PR tackles some points from #598, focused on #598 (comment) as agreed on the team meeting

Link to the built documentation
I still have issues with displaying images, will investigate this.

docs/faq.md

README.md

Hrovatin · 2025-10-27T07:57:24Z

docs/userguide/userguide.md

-the bayesian optimization loop, how it can be configured and 
+the Bayesian optimization loop, how it can be configured and 
 how the results can be post-analysed.



Comments from before:

I found the description of parameters as "individual degrees of freedom" a bit too technical. I am not sure if this term is familiar for all users and would suggest to name it "variables that can be adjusted during an experiment" or something similar.

Descriptive vs active language

@AdrianSosic @AVHopp @Scienfitz Let me know if I should fix any of these as well

I can live with both descriptive and active language as long as it is consistent. Agree with the point of the description for parameters being too technical. Maybe one could use something describing that the parameters are the things controlling the experiments and that can be changed by the experimentalist?

Maybe for Parameters:
"Parameters to be optimized and other data covariates."

If you sue the word covariates you will make it even more technical than the original wording

Would be "Parameters to be optimized and additional dataset information" better?

Why the "additional dataset information", what do you mean by that?

I agree thats imo more confusing than the original as well

why not simply individual settings you can control during an experiment

With additional dataset information I meant like task type (which is not optimized per se). But I can simplify.
@Scienfitz your sounds ok, but would replace "settings" with "variables" or so?

+1 for consistency:

If you go with Martin's suggestion (regardless of settings or variables), let's not add a you

Let's also resolve the other inconsistencies you pointed out above

AVHopp · 2025-10-28T08:09:09Z

@Hrovatin please have a compiled version of this on your fork and link it here (ideally in the PR description) since this makes it way easier to review. If there is trouble with deploying things on your fork just ping me and I can help with that :)

AVHopp · 2025-10-28T08:10:25Z

Also, can you check where you branched off for this PR? Just switched the branch to view the README on github and this seems to be quite outdated

AVHopp

First few comments :)

docs/_static/complex_search_space_automatic.svg

README.md

docs/faq.md

Updated changelog to reflect recent changes and fixes.

README.md

Hrovatin · 2025-11-04T14:46:29Z

README.md

+
+<div align="center">
+
+[![Complex Search Space](https://raw.githubusercontent.com/Hrovatin/baybe/docs/easy_access/docs/_static/complex_search_space_automatic.svg)](https://github.com/emdgroup/baybe/)


Note: This requires mini PR of uploading images before merge and updating the link

Some context from my end as we investigated this: The issue is that Sphinx has problems trying to load the static file directly from the repo here: You can either give it a path such that it finds it in the README on github but not in the compiled version or vice versa. Hence the fix to link to the static image on github itself.

Hrovatin · 2025-11-04T14:46:53Z

README.md

+
+<div align="center">
+
+[![Quick Start](https://raw.githubusercontent.com/Hrovatin/baybe/docs/easy_access/docs/_static/quick_start_automatic.svg)](https://github.com/emdgroup/baybe/)


Note: This requires mini PR of uploading images before merge and updating the link

Some context from my end as we investigated this: The issue is that Sphinx has problems trying to load the static file directly from the repo here: You can either give it a path such that it finds it in the README on github but not in the compiled version or vice versa. Hence the fix to link to the static image on github itself.

AdrianSosic

Hi @Hrovatin, thanks for taking the lead here. I'm welcoming improvements to the README 👍🏼 But we have to make sure that this is not at the cost of:

introducing inconsistencies
a lack of precision, i.e. softening the language in such a way that statements become inexact

To show you what I mean, I've added the hashtags #consistency and #rigor to many of my comments. This is only a first round anyway, more comments to come, but I'll now first go over the other existing open threads 🙃

AdrianSosic · 2025-11-05T08:28:35Z

README.md

- 📈 Comprehensive backtest, simulation and imputation utilities: Benchmark and find your best settings
- 📝 Fully typed and hypothesis-tested: Robust code base
- 🔄 All objects are fully (de-)serializable: Useful for storing results in databases or use in wrappers like APIs
+- 📚 Leverage **domain knowledge**.  


#consistency

Maybe this is just me, but: I personally have the impression that a nested list of features is visually actually much more overwhelming than the flat list we had before.

Before we had:

one line per bullet (there was one exception that should have been fixe)

Same style per bullet. First: named feature. Second: short explanation

Now we have:

Mixed multi-level bullets (sometimes one entry, sometimes with headings)

Drastically different lengths of the features descriptions

Completely mixed styles. Sometimes, there is a feature name before a colon, sometimes there is no colon and sometimes there is not even a feature name. Sometimes, there is a bold section, sometimes not. Sometimes, the style is imperative mood (e.g "Encode ...") and sometimes it's just listing facts

To be honest, I don't understand how this is now "simpler" than what used to be there before (not talking about content/wording, but just about formatting) 😅 What are your thoughts on this, @AVHopp @Scienfitz

If all of you prefer the nested style, I'm fine with it. But can we then at least fix the other inconsistencies?

I always aimed to start with why and then optionally go to how. I do not think that the name of the feature is the first thing to read as that may be technical, but rather the purpuse that everyone be able to see the relevance of. I realize now that a few are not worded that way so I made push that unifies that part.

I like nested format as it groups things a bit instead of having a laundry list of everything together. But if the groupping does not make sense we can re-discuss.

I added bolding to all first-level titles, but I can also add bold parts to others.

I made all imperative as this is closer to what was before.

I personally do not see somewhat different line lengths as major issue, but if all other see it then we can re format.

README.md

AdrianSosic · 2025-11-05T08:38:56Z

README.md

+- 📚 Leverage **domain knowledge**.  
+  - 🎨 Encode categorical data to capture relationships between categories. BayBE also provides built-in chemical encodings.
+  - 🛠️ Option to build-in mechanistic process understanding via custom surrogate models.
+- 🏛️ Leverage **historic data** to accelerate optimization via transfer learning.


#rigor

I think this is potentially very confusing / misses the point. All of Bayesian optimization is built upon the idea of using "historic" data, if you will. The term simply isn't well-enough specified here to make the point. The important part is that the data needs to come from slightly different campaigns (message of the old bullet) and not just represent "historic stuff" that you've collected earlier on with the same setup.

Changed to Leverage **historic data** from similar campaigns to accelerate optimization via transfer learning.

README.md

AdrianSosic · 2025-11-05T10:19:19Z

README.md

+
+</div>
+
+From the user perspective, the most important part is the "design" step.


#rigor

Perhaps no one of you noticed, but I still think this is a very critical points since highly misleading. With "design", you refer to the step where the user defines the components of the the campaign etc. However, please note that we're fully in the DOE context here, where "design" has a very different meaning – it's literally in the name of the approach. In (Bayesian) DOE, the "design" refers to the entire end-to-end process, i.e. it also includes (and one could argue this is actually the main part of it!) the actual placement of the experiments in the search space according to some criterion – so that would correspond not the parameter definition step but actually to the recommendation step.

Thus, I think it's crucial that we adjust the terminology here (and also in the "design" user guide)

just call it setup step or similar to avoid the word design

@AdrianSosic would "setup" be ok?

docs/faq.md

AdrianSosic · 2025-11-05T12:42:07Z

docs/_static/quick_start_dark.svg

Here we have again the "parameter combination" term (see other thread)

Analogously, maybe we should make it Measure targets below

I really don't like the icon for the uppermost layer – it's way too complicated / cluttered for this purpose. Isn't there something simpler? E.g. a pen with a "clean" paper, or maybe just a pen, or similar

I know it's a bit pedantic, and hopefully we'll soon be able to replace it with a proper logo anyway, but can you make the boundaries around the BayBE part a tiny little broader (not by much). But it really looks like a bad screeenshot :D

Will do all of them at the end. @Scienfitz @AVHopp Please also let me know if you have any requests fro this plot before I change it

is the color (orange and blue) of the arrows intentional? seems strange to me I would just make them neutral

Co-authored-by: AdrianSosic <[email protected]>

…ter values)

Hrovatin requested review from AVHopp, AdrianSosic and Scienfitz as code owners October 23, 2025 14:40

Hrovatin marked this pull request as draft October 23, 2025 14:41

Scienfitz assigned Hrovatin Oct 24, 2025

Hrovatin marked this pull request as ready for review October 24, 2025 14:42

This comment was marked as outdated.

Sign in to view

Hrovatin commented Oct 24, 2025

View reviewed changes

docs/faq.md Outdated Show resolved Hide resolved

Hrovatin commented Oct 24, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

Hrovatin commented Oct 24, 2025

View reviewed changes

README.md Show resolved Hide resolved

Hrovatin commented Oct 27, 2025

View reviewed changes

AVHopp reviewed Oct 28, 2025

View reviewed changes

Hrovatin added 16 commits October 28, 2025 10:12

Designing experiments checklists FAQ - unfinished

3e67eb0

Expand checklist

24559ad

Add design checklist to FAQ

9785796

Make introduction clearer

6a4cdb7

Format readme introduction

22718e0

Simplify readme introduction language

2fa2190

Move API overview diagram into this repository

6d9baf3

Rename API overview drawio file

e74be96

Make drawio template quick start diagram

beb9b9c

Add quick start diagram

d58148a

Add complex searchspace drawio diagram

93b2e81

Update diagram

6f6f4ac

Make readme more accessible for new users

c09a626

Format FAQ

1832a47

Update changelog

0e293b2

Updated changelog to reflect recent changes and fixes.

Add a few more examples

0da883e

Hrovatin commented Oct 30, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

Hrovatin added 14 commits October 30, 2025 06:37

rweord

5584eb1

Add example use case

75718b5

Remove oxford comma

b1aaa0e

typo

60c8f0e

reword

af543f9

Fix file name typo

08ee66b

Try not using svg with automatic light/dark mode

8c3b9f3

fix image links in readme

cf01ac2

Remove changelog entry

4f17ccd

Fix typo

2ddcf59

Remove unnecessary wording

16588c3

Reword to match API terms properly

6cf645c

Reword to properly match the API wording

186e6b4

Fix readme image links

12318cf

Hrovatin commented Nov 4, 2025

View reviewed changes

AdrianSosic requested changes Nov 5, 2025

View reviewed changes

AdrianSosic reviewed Nov 5, 2025

View reviewed changes

Hrovatin and others added 10 commits November 5, 2025 15:34

reword

9b1c809

Co-authored-by: AdrianSosic <[email protected]>

reword

522ee1d

Co-authored-by: AdrianSosic <[email protected]>

reword

7ad39d1

Co-authored-by: AdrianSosic <[email protected]>

reweord

451c99b

Reword features

7bdd5a5

Reword user to you

1d13bf0

Unify wording of setting (BO method) and configuration (chosen parame…

b2d38c9

…ter values)

Fix rendering style

e81c2c2

reword

eb701cf

Remove setup checklist

07d4f98

Hrovatin mentioned this pull request Nov 6, 2025

Guide for setting up the campaign #690

Closed


		<div align="center">

		[![Complex Search Space](https://raw.githubusercontent.com/Hrovatin/baybe/docs/easy_access/docs/_static/complex_search_space_automatic.svg)](https://github.com/emdgroup/baybe/)


		<div align="center">

		[![Quick Start](https://raw.githubusercontent.com/Hrovatin/baybe/docs/easy_access/docs/_static/quick_start_automatic.svg)](https://github.com/emdgroup/baybe/)


		</div>

		From the user perspective, the most important part is the "design" step.

Improve docs accessibility #676

Are you sure you want to change the base?

Improve docs accessibility #676

Conversation

Hrovatin commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Hrovatin Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AVHopp commented Oct 28, 2025

Uh oh!

AVHopp commented Oct 28, 2025

Uh oh!

AVHopp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AdrianSosic left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AdrianSosic Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Hrovatin commented Oct 23, 2025 •

edited

Loading

Hrovatin Oct 27, 2025 •

edited

Loading

AdrianSosic Nov 5, 2025 •

edited

Loading