Hyperparameter tuning is one of those tasks that almost everyone does badly and almost nobody admits to. The standard approach is a nested loop over a grid somebody picked by feel, run overnight, with the results recorded in a notebook cell that gets overwritten the next day. Optuna exists to replace that, and its documentation is one of the better pieces of library writing in the Python machine learning ecosystem. The structure is sensible.
Installation, then a tutorial split into key features and recipes, then a full API reference, then an FAQ that is unusually good. The key features section covers the concepts, the recipes section covers the things you will actually need to do, and the separation means you can learn the ideas without wading through configuration and then find the configuration when you need it. The define-by-run API is the central design idea and the documentation explains it well. Instead of declaring a search space up front, you write ordinary Python and call suggest methods inside your objective function.
This means your search space can be conditional, so you can suggest a number of layers and then suggest a width for each layer, or pick an optimiser and then suggest only the parameters that optimiser has. Anyone who has fought a grid search into representing a conditional space will understand immediately why this matters. The docs get you to that understanding quickly. Pruning is the part I would make people read.
Optuna can stop unpromising trials early rather than training every one to completion, and on any real training job that is the difference between a search you can afford and one you cannot. The documentation covers the pruners, explains how they interact with the reporting you have to add to your training loop, and is honest that aggressive pruning can kill trials that would have recovered. That last point is the kind of caveat that documentation usually omits, and its presence raises my confidence in the rest. Visualisation and the Optuna Dashboard get proper coverage.
Optimisation history, parameter importance, parallel coordinate plots and slice plots are all straightforward to produce, and the importance plots in particular are worth running because they usually reveal that two of your eight hyperparameters matter and the rest are noise. That finding, repeated across projects, would change how most people spend their time. OptunaHub is the newer community feature sharing platform and its documentation is thinner, which is reasonable for something still growing. Now the criticisms.
The first is philosophical and applies to the entire category rather than to Optuna specifically. Nothing in this documentation tells you that hyperparameter optimisation is usually the least valuable thing you can do to improve a model. More data, better data, fixing your labels, fixing your validation split, better features, and choosing a more appropriate model class all typically beat tuning by a wide margin. Tuning is appealing because it is mechanical and feels like progress.
A short section saying so would improve the outcomes of everyone who reads this library's docs, and no library author is ever going to write it. Sampler choice is underexplained relative to how much it matters. The default is TPE and it is a good default, and CMA-ES, grid, random and the various specialist samplers each have situations where they win. The reference describes what each one does.
It does considerably less to help you decide, and the decision has a real effect on how many trials you need. The parallel and distributed documentation is adequate for the simple case of several workers sharing a storage backend and gets vaguer once you want anything more elaborate. Given that the reason to use a framework like this is often to run many trials across many machines, that is a slightly awkward soft spot. There is also an assumption running through everything that you know how to evaluate a model correctly.
The objective function you optimise is the thing that determines what you get, and if you tune against a validation split that leaks, you will efficiently find the hyperparameters that overfit fastest. The documentation is not obliged to teach cross validation and it would be improved by a warning about it, because tuning is exactly where leakage does the most damage. My four point two is for clear teaching of a well designed library, unusually honest caveats, and a tutorial that gets you productive quickly. The marks come off for what surrounds the tool rather than the tool itself, which is the judgement about whether to be tuning at all.