Skip to content

Reorganization of user guides and issues #677

@AVHopp

Description

@AVHopp

We realized that the organization of both the user guides and the examples needs to be improved. This will involve the introduction of new ways of categorizing pages within the documentation as well as reorganizing the actual content of the documentation.
The core idea is to organize the documentation into Components, Concepts, Examples and Guidance:

  • A Component is a piece of BayBE that needs to work together with other Components, like the recommenders, the objectives and so on.
  • A Concept is a something that is not tied to individual parts of BayBE but rather the things that you can do with BayBE and the features that we want to include into BayBE, like Transfer Learning, Active Learning, Pareto Optimization.
  • An Example is a python script that can be run end-to-end and demonstrates a certain aspect or Concept of BayBE, while ideally being focused on a specific and clear use case. An example for this is the current laser tuning example which is used to demonstrate the Concept of Transformations
  • Guidance describe the role of BayBE as well as all of its parts in the general BO loop and framework and how to use this. Such aGuidance would for example explain how to model a search space or which recommender to choose.

We currently plan to implement these by first working on the following user guides:

  • In general, organize the existing documentation into Component, Concept, Example and Guidance
  • Campaign: Some parts of this would be better placed in other user guides, like the information about batch optimization.
  • Constraints: Split this monolithic guide into several smaller ones, and provide an abstract overview. This will however only be done after a refactoring of the constraints.
  • Environment variables: This will probably be no longer necessary after the implementation of Settings #662 .
  • Insights: This might become its own category in the future, but for now, this will be kept as-is and be moved into a Component
  • Parameters: This will probably be handled similar to how we handle constraints, and will probably be kept for now.
  • Recommenders Will be changed into a Component and will get a Guidance.
  • Search spaces: This user guide needs a general major refactoring and needs to explain the conceptual differences between the different kinds of search spaces.
  • Simulation: Will be investigated in detail after the refactoring of the simulation submodule
  • Surrogates: This needs an (additional) Guidance
  • Utilities: Will be kept for now, but it is unclear how to categorize it.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions