# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@octobus.net>
# Date 1660749312 -7200
#      Wed Aug 17 17:15:12 2022 +0200
# Node ID 380e445784a18595212da6f311efbd68ad0c6299
# Parent  9523c56c8dff717c47487277deef8e447cb2bf28
Add a basic doc file

If it currently very basic be should create a base to extend in the future.

diff --git a/docs/concept.rst b/docs/concept.rst
new file mode 100644
--- /dev/null
+++ b/docs/concept.rst
@@ -0,0 +1,80 @@
+===================================================
+General Concepts for Poulpe Performance tools Suite
+===================================================
+
+General philosophy
+==================
+
+(and far too many other stuff as we have a single doc files for now)
+
+Building blocks
+===============
+
+Data Environment
+----------------
+
+Data environment are directory that contains data to be used in a benchmark.
+
+Inside each tarball is a data-env.poulpe file, which specifies the data source,
+metadata and arguments and transformations needed to setup for a benchmark.
+
+Binary Environment
+------------------
+
+A directory containing a bin-env.poulpe file that describe the binary
+environment and a `bin-env.shell` to provide us with a shell within that binary
+environment.
+
+Currently we use `mercurial.poulpe-setup.sh` to setup new bin-env.shell.
+
+Benchmark
+---------
+
+A `xxx.pdb` file that describe how to run a specific benchmark and its variant
+
+Running benchmarks
+==================
+
+Individual Runs
+---------------
+
+Each benchmark can be run individually. This give a use more flexibility to run
+comparative run, schedule runs and debug faulty ones.
+
+This is done through the `run-util` executable
+
+Results
+-------
+
+Each results can be manipulated and compared individually.
+
+They can exists as `xxx.pbr` files. Having option to group them (for example) in
+a database will be necessary for scaling
+
+Scheduling
+----------
+
+Scheduling is currently minimal and will need further improvement in the futur.
+
+The scheduling install new bin-envs and cleans up older one.
+
+New case are autogenerated using the `auto-cases` executable and the overall logic lives in
+`loop` executable. the `upload` is done using the `upload` executable.
+
+Using results
+=============
+
+Viewing
+-------
+
+The `env-desc` executable can be used to see the content of a `xxx.pbr` files.
+
+Comparing
+---------`
+
+The `env-desc` executable can be used to see the content of a `xxx.pbr` files.
+
+Searching
+---------
+
+There are no easy way to search result just yet