diff --git a/doc/development/create_your_own_sequence.rst b/doc/development/create_your_own_sequence.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3cd7d485cc44474793406832e3c6c06fb91d8505
--- /dev/null
+++ b/doc/development/create_your_own_sequence.rst
@@ -0,0 +1,119 @@
+How to define your own sequence to build an NXtomo
+==================================================
+
+Design
+""""""
+
+The conversion process is done as follow:
+
+.. image:: img/nxtomomill_design_1.png
+
+The first step this can be done two ways
+
+.. image:: img/nxtomomill_design_2.png
+
+Until now we were only using the title to deduce the acquisition and the type of frames of each Bliss entry.
+
+But the `FRAME_TYPE_SECTION` allow us to ignore those titles and define manually the sequence of the acquisition.
+
+
+Coming back to the `FRAME_TYPE_SECTION` section
+
+`FRAME_TYPE_SECTION` section
+''''''''''''''''''''''''''''
+
+If this section is fill then the `ENTRIES_AND_TITLES_SECTION` will be ignored. Those are mutually exclusive sections.
+
+From it we can define `data_scans` that allow us to define a sequence of scan defining an acquisition using [url](https://fr.wikipedia.org/wiki/Uniform_Resource_Locator). Like:
+
+.. code-block:: text
+
+ data_scans = (
+ (frame_type=projections, entry=silx:///path/to/file?/path/to/scan/node,),
+ (frame_type=projections, entry=/path_relative_to_file),
+ )
+
+Here we will create one acquisition from `silx:///path/to/file?/path/to/scan/node` to be used as a set of projections and `/path_relative_to_file` as a set of projections to.
+
+.. note::
+
+ Url can be relative to different file
+
+.. warning::
+
+ The created acquisition will follow the provided order
+
+
+Example: create an NXtomo using the `data_scans` field
+""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Using the configuration file
+''''''''''''''''''''''''''''
+
+You can find a file `conversion_using_data_scans.cfg` in the `solution` folder that create an acquisition using `data_scans`:
+
+
+.. image:: img/nxtomomill_example_data_scans.png
+
+
+It can be executed by calling:
+
+.. code-block:: bash
+
+ nxtomomill h52nx --config conversion_using_data_scans.cfg
+
+Using the python API
+''''''''''''''''''''
+
+.. code-block:: python
+
+ from nxtomomill.converter import from_h5_to_nx
+ from nxtomomill.io.config import TomoHDF5Config
+ from nxtomomill.io.framegroup import FrameGroup
+ from silx.io.url import DataUrl
+
+ input_file_path = "bambou_hercules_0001.h5"
+
+ configuration = TomoHDF5Config()
+ configuration.input_file = input_file_path
+ configuration.output_file = "bambou_hercules_0001.nx"
+ configuration.data_frame_grps = (
+ FrameGroup(
+ url=DataUrl(
+ file_path=input_file_path,
+ data_path="1.1",
+ scheme="silx",
+ ),
+ frame_type="initialization",
+ ),
+ FrameGroup(
+ url=DataUrl(
+ file_path=input_file_path,
+ data_path="2.1",
+ scheme="silx",
+ ),
+ frame_type="darks",
+ ),
+ FrameGroup(
+ url=DataUrl(
+ file_path=input_file_path,
+ data_path="3.1",
+ scheme="silx",
+ ),
+ frame_type="flats",
+ ),
+ FrameGroup(
+ url=DataUrl(
+ file_path=input_file_path,
+ data_path="4.1",
+ scheme="silx",
+ ),
+ frame_type="projections",
+ ),
+ )
+
+ res = from_h5_to_nx(configuration=configuration)
+
+.. note::
+
+ you will see another way to create an NXtomo from scratch that could be another alternative.
diff --git a/doc/development/img/nxtomomill_design_1.png b/doc/development/img/nxtomomill_design_1.png
new file mode 100644
index 0000000000000000000000000000000000000000..1d1ed786c01cb83a37c90710cec9a5c3f50105b0
Binary files /dev/null and b/doc/development/img/nxtomomill_design_1.png differ
diff --git a/doc/development/img/nxtomomill_design_2.png b/doc/development/img/nxtomomill_design_2.png
new file mode 100644
index 0000000000000000000000000000000000000000..1a8d34a1373b76af5bcccd6c69036c2e460d32a0
Binary files /dev/null and b/doc/development/img/nxtomomill_design_2.png differ
diff --git a/doc/development/img/nxtomomill_example_data_scans.png b/doc/development/img/nxtomomill_example_data_scans.png
new file mode 100644
index 0000000000000000000000000000000000000000..ab7f263e03faf6e184d5f90c3176b3479c372663
Binary files /dev/null and b/doc/development/img/nxtomomill_example_data_scans.png differ
diff --git a/doc/development/index.rst b/doc/development/index.rst
index 1a337f8923c3a54e051627073484efddffbdaca3..340ba619808a30e563e47e6a9d77508bb758c3fc 100644
--- a/doc/development/index.rst
+++ b/doc/development/index.rst
@@ -6,3 +6,4 @@ Development
changelog.rst
design/index.rst
+ create_your_own_sequence.rst
diff --git a/doc/tutorials/h52nx.rst b/doc/tutorials/h52nx.rst
index f1f2ece061cd2000a7e3ac930fc213974e185e59..be37985af2ceeeeb49f084873c44248013c2ed93 100644
--- a/doc/tutorials/h52nx.rst
+++ b/doc/tutorials/h52nx.rst
@@ -249,3 +249,8 @@ If it exist then it will be picked by *nxtomomill h52nx* instead of the ``data``
.. hint::
You can find `here a script casting a dataset to another type <https://gitlab.esrf.fr/tomotools/scripts/-/blob/master/cast_detector_dataset.py>`_
+
+
+.. hint::
+
+ Consult section on :ref:`handling_h52nx_issues` in case of troubles.
diff --git a/doc/userguide/user_corner.rst b/doc/userguide/batch_processing.rst
similarity index 97%
rename from doc/userguide/user_corner.rst
rename to doc/userguide/batch_processing.rst
index 8d7c6ecd0ae681d89a029b8e19030031d4449458..89bd6b6e8a559a58a43484b003063a2f5312652d 100644
--- a/doc/userguide/user_corner.rst
+++ b/doc/userguide/batch_processing.rst
@@ -1,8 +1,5 @@
-User corner
-===========
-
Batch processing
-****************
+================
It can be convenient to convert several file in a row. Here are two small examples around h52nx that can be reused for other nxtomomill applications.
diff --git a/doc/userguide/handling_h52nx_issues.rst b/doc/userguide/handling_h52nx_issues.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e3b535c2d2907703921040019171272745c71362
--- /dev/null
+++ b/doc/userguide/handling_h52nx_issues.rst
@@ -0,0 +1,163 @@
+.. _handling_h52nx_issues:
+
+How to handle `h52nx` conversion issues
+=======================================
+
+This section present ways to go around some potential issues during conversion from bliss-scan to NXtomo like:
+
+* some bliss entry is skipped / unrecognized
+* some mandatory information are missing
+* specify some field values
+* provide a `h52nx` configuration file to tomwer
+
+
+Some bliss entry is skipped / unrecognized
+""""""""""""""""""""""""""""""""""""""""""
+
+Currently the deduction of a bliss scan type (dark, flat, projection...) is done by:
+
+* looking at the 'technique' group (image_key dataset)
+* else look at the title. Title mapping is defined in settings.py file of nxtomomill.
+
+If the titles have a specific naming convention then you can provide updated information to one of the following:
+
+* modify it from the settings.py file (if this is a local installation
+* provide different name to be used
+
+ * from the CLI
+ * from a configuration file (see later)
+ * from the python API
+
+.. hint::
+
+ You can 'ignore' the bliss 'technique' dataset (aka bliss tomo config) by using a configuration and turning the `ignore_bliss_tomo_config` to True
+
+From the CLI without a configuration file
+'''''''''''''''''''''''''''''''''''''''''
+
+If you look at the help you can see how to redefine title names.
+
+.. code-block::
+
+ nxtomomill h52nx --help
+
+ --init_titles: mark the beginning of a Bliss sequence (eq acquisition). Use for example to retrieve energy.
+ --dark_titles: specify that this Bliss entry is relative to dark field
+ --flat_titles: specify that this Bliss entry is relative to flat field
+ --proj_titles: specify that this Bliss entry is relative to projection
+ --align_titles: specify that this Bliss entry is relative to alignment (some time called 'return')
+ --init_zserie_titles, --init_pcotomo_titles same as init-titles but dedicated to zseries and pcotomo (behavior of NXtomo creation is a bit different)
+
+
+From the CLI with the configuration file
+''''''''''''''''''''''''''''''''''''''''
+
+The same information can be provided to `ENTRIES_AND_TITLES_SECTION` section
+
+
+.. image:: img/handling_h52nx_issues/nxtomomill_config_titles_section.png
+
+
+From the python API
+'''''''''''''''''''
+
+you can also provide this information to the `TomoHDF5Config` class like:
+
+.. code-block:: python
+
+ configuration = TomoHDF5Config()
+ configuration.init_titles = ("mytomo:basic", "mytomo:fullturn")
+
+
+Some mandatory information are missing
+""""""""""""""""""""""""""""""""""""""
+
+From the CLI without a configuration file
+'''''''''''''''''''''''''''''''''''''''''
+
+There is a limited number of information that the user can provide manually like energy or pixel size. Those can be provided from the set-params option like:
+
+In this case you can provide it from the --set-params option from the CLI like:
+
+nxtomomill h52nx ... --set-params energy 0.5
+
+.. warning::
+
+ the `--set-params` option should always be put at the end of the command. Because it can take a full list of sub-options
+
+From the CLI with a configuration file
+''''''''''''''''''''''''''''''''''''''
+
+You can also provide this information to the configuration file under the `EXTRA_PARAMS_SECTION` section like:
+
+.. image:: img/handling_h52nx_issues/nxtomomill_configuration_file_extra_params.png
+
+
+From the python API
+'''''''''''''''''''
+
+Or provide this from a python script when defining the configuration
+
+.. code-block:: python
+
+ configuration = TomoHDF5Config()
+ configuration.param_already_defined = {
+ "energy_kev": 19.2,
+ }
+
+
+Specifying field values
+"""""""""""""""""""""""
+
+For specific fields ("detector name", "translation_x", "translation_y", "translation_z", and "rotation"), we attempt to extract this information from the 'technique' dataset. If the data is not available there, we revert to the generic behavior.
+
+Generic behavior
+''''''''''''''''
+The generic behavior involves searching for each field in a set of predefined locations or paths. If the dataset's structure matches the expected format, the field value is retrieved from the corresponding location.
+
+Customizing locations
+'''''''''''''''''''''
+
+You can customize these locations (similar to titles) using the following methods:
+* `settings.py file <https://gitlab.esrf.fr/tomotools/nxtomomill/-/blob/master/nxtomomill/settings.py>`_: modify this file to change the default locations parsed.
+* command line options.
+* `h52nx` configuration file: overwrite the locations from a configuration file.
+
+From the CLI without a configuration file
+'''''''''''''''''''''''''''''''''''''''''
+
+For the CLI we can get them using ̀`nxtomomill h52nx --help` again:
+
+* `--x_trans_keys`: x translation key in bliss HDF5 file.
+* `--y_trans_keys`: y translation key in bliss HDF5 file.
+* `--z_trans_keys`: z translation key in bliss HDF5 file.
+* `--sample-detector-distance`: sample detector distance.
+* `--valid_camera_names`: Valid NXDetector dataset name to be considered. If None will try to deduce the NXdetector from attributes and shape of the dataset
+* `--rot_angle_keys`: Valid dataset name for rotation angle. If None, look name from "technique/scan/motor"
+* `--acq_expo_time_keys`: acquisition exposure time in bliss HDF5 file.
+* `--x_pixel_size_key` x pixel size key in bliss HDF5 file.
+* `--y_pixel_size_key` y pixel size key in bliss HDF5 file.
+
+From the CLI with a configuration file
+''''''''''''''''''''''''''''''''''''''
+
+the same field are available on the `KEYS_SECTION` of the configuration file.
+
+.. image:: img/handling_h52nx_issues/nxtomomill_config_keys_section.png
+
+dataset discovery is done as follow:
+
+* converter will first look at `positioner` group to resolve key then at `root` group aka bliss entry*. Collect is done by a look like code:
+
+.. code-block:: python
+
+ for parse_group in (positioner, root_aka_bliss_entry):
+ # first step: look for existing dataset with expected number of elmt
+ for key_checked in parse_group:
+ if find_dataset_with_expected_nb_elment:
+ return it
+ # second step: look for existing dataset and adapt it if not enought elmt
+ for key_checked in parse_group:
+ if find_dataset:
+ return it
+ return None
diff --git a/doc/userguide/img/handling_h52nx_issues/nxtomomill_config_keys_section.png b/doc/userguide/img/handling_h52nx_issues/nxtomomill_config_keys_section.png
new file mode 100644
index 0000000000000000000000000000000000000000..5d5707e7a2a203590de233f1b17f9f02763eb90c
Binary files /dev/null and b/doc/userguide/img/handling_h52nx_issues/nxtomomill_config_keys_section.png differ
diff --git a/doc/userguide/img/handling_h52nx_issues/nxtomomill_config_titles_section.png b/doc/userguide/img/handling_h52nx_issues/nxtomomill_config_titles_section.png
new file mode 100644
index 0000000000000000000000000000000000000000..891ee056b81711f9714d04e0fe6a04301720346b
Binary files /dev/null and b/doc/userguide/img/handling_h52nx_issues/nxtomomill_config_titles_section.png differ
diff --git a/doc/userguide/img/handling_h52nx_issues/nxtomomill_configuration_file_extra_params.png b/doc/userguide/img/handling_h52nx_issues/nxtomomill_configuration_file_extra_params.png
new file mode 100644
index 0000000000000000000000000000000000000000..01e3811c3dc4bf1ae1cea98fa16ac901e3721dc8
Binary files /dev/null and b/doc/userguide/img/handling_h52nx_issues/nxtomomill_configuration_file_extra_params.png differ
diff --git a/doc/userguide/index.rst b/doc/userguide/index.rst
index 3410f966088259ee50e579621b72e61bc7d451b4..d6927ba691a6a0ee4ddcff7258e29230c07c1ede 100644
--- a/doc/userguide/index.rst
+++ b/doc/userguide/index.rst
@@ -5,5 +5,6 @@ User Guide
:maxdepth: 1
installation.rst
- user_corner.rst
- settings.rst
\ No newline at end of file
+ batch_processing.rst
+ settings.rst
+ handling_h52nx_issues.rst
\ No newline at end of file