doc: let's document the framework

refs #143

docs/README.md

@@ -1,3 +1,20 @@
 # What is ConcreteFHE
 
-To be done
+## Introduction
+
+ConcreteFHE, or Concrete for short, is a python package which aims to simplify the use of so-called fully homomorphic encryption (FHE) for datascientists. FHE is a new powerful cryptographic tool, which allows e.g. servers to perform computations directly on encrypted data, without needing any kind of secret key. With FHE, privacy is at the center, and one can build services which ensure full privacy of the user and are the perfect equivalent of their unsecure counterpart. FHE is also a killer feature regarding data breaches: as anything done on the server is done over encrypted data, even if the server is compromised, there is in the end no leak of any kind of useful data.
+
+Concrete framework is made of several parts:
+- a library, called concrete-lib, which contains the core cryptographic API's for computing with FHE
+- a compiler, called concrete-compiler, which allows to turn an MLIR program into an FHE program, on the top of concrete-lib
+- some frontends, which convert different langages to MLIR, to finally be compiled.
+
+In the first version of Concrete framework, there is a single frontend, called concrete-hnp, which is the equivalent of numpy. With our toolchain, a data scientist can convert a numpy program into an FHE program, without any a-priori knowledge on cryptography.
+
+## Organization of the Documentation
+
+Basically, we have divided our documentation into several parts:
+- one about basic elements, notably description of the installation, that you are currently reading
+- one dedicated to _users_ of Concrete, with tutorials, how-to's and deeper explanations
+- and finally, one dedicated to _developpers_ of Concrete, who could be internal or external contributors to the framework
+

docs/dev/explanation/MLIR.md

@@ -1,4 +1,4 @@
 # MLIR
 
-to be done
+To be done by Ayoub, #311
 

docs/dev/howto/DOCUMENTING.md

@@ -1,7 +1,7 @@
 
 # Documenting
 
-## Making docs with Sphinx
+## Using Sphinx
 
 One can simply create docs with Sphinx and open them, by doing:
 
@@ -9,7 +9,9 @@ One can simply create docs with Sphinx and open them, by doing:
 make docs
 ```
 
-The documentation contains both files written by hand by developpers and files automatically created by parsing the source files.
+Remark that this needs to be done in docker.
+
+The documentation contains both files written by hand by developpers (the .md files) and files automatically created by parsing the source files.
 
 ### Opening doc
 

docs/index.rst

@@ -24,9 +24,7 @@ Homomorphic Development Kit's documentation
 
    user/howto/COMPILE.md
    user/howto/REDUCE_NEEDED_PRECISION.md
-   user/howto/DEBUG.md
-   user/howto/SUBMIT_ISSUE.md
-   user/howto/SUPPORT.md
+   user/howto/DEBUG_SUPPORT_SUBMIT_ISSUES.md
    user/howto/FAQ.md
 
 .. toctree::

docs/user/explanation/FHE_LIMITS.md

@@ -1,2 +1,3 @@
 # FHE Limits
 
+Benoit to do: write it

docs/user/explanation/FUTURE_FEATURES.md

@@ -1,2 +1,3 @@
 # Future Features
 
+Alex to do: #321

docs/user/explanation/QUANTIZATION.md

@@ -1,2 +1,3 @@
 # Quantization
 
+Arthur to do: #319

docs/user/explanation/WHAT_IS_FHE.md

@@ -1 +1,3 @@
 # What is FHE?
+
+Benoit to do: write it

docs/user/howto/COMPILE.md

@@ -1 +1,4 @@
 # Compiling
+
+Umut or Arthur, who wants to do this part?
+

docs/user/howto/DEBUG.md

@@ -1 +0,0 @@
-# Debugging

docs/user/howto/DEBUG_SUPPORT_SUBMIT_ISSUES.md

@@ -0,0 +1,59 @@
+# Debugging / Support / Submitting Issues
+
+First, let's not forget that this version of Concrete framework is a beta product, meaning that it is not completely polished, contains several bugs (would they be known or unknown at this time). Also, let's not forget that FHE is an highly hot topic, and notably, that it cannot be considered as a solved problem.
+
+Anyway, let's list some ways to debug your problems here. If nothing seems conclusive, you can still report the issue, as explained in a later section of this page.
+
+## Is it a bug by the framework or by the user?
+
+If ever your numpy program fails, it may be because:
+- of bugs due to Concrete framework
+- of bugs due to the user, notably who would not use the framework as expected or not consider the limits of the framework.
+
+For the latter kind of bugs, we encourage the user to have a look to:
+- the error message she gets
+- the documentation of the product
+- the known limits of the product (such as the reduced set of supported operations at this time, or the limited precision of the computations).
+
+Once the user has tried to see if the bug was not her own, it is time to go further.
+
+## Having a reproducible bug
+
+Once you're sure it is a bug, it would be nice to try to
+- make it highly reproducible: e.g., by reducing as much the randomness as possible; e.g., if you can find an input which fails, there is no reason to let the input random
+- reduce it to the smallest possible bug: it is easier to investigate bugs which are small, so when you have an issue, please try to reduce to a smaller issue, notably with less lines of code, smaller parameters, less complex function to compile, faster scripts etc
+
+## Asking the community
+
+We have created a Slack channel (TODO: LINK TO BE ADDED), such that you can directly ask the developpers and community about your issue.
+
+Hopefully, it is just a misunderstanding or a small mistake on your side, that one can help you fix easily. And, the good point with your feedback is that, once we have heard the problem or misunderstanding, we can make the documentation even clearer (such as, increasing the FAQ).
+
+## Having a look to the compilation artifacts
+
+When things are more complicated, or if you want to have a look by yourself, you may want to have a look to the compilation reports, which are called artifacts. This is as simple as described in [TODO: add the link to the tutorial about having artifacts].
+
+This function will create a directory, containing notably:
+[TODO: Umut to fix / complete the following information]
+- bounds.txt: a file describing the expected ranges of data in the different steps of the computation
+- cryptographic_parameters.txt: a file describing the different keys
+- ir_nodes.txt: a file describing the different nodes in the intermediate representation (IR)
+- optimizations_applied.txt: a file describing the different optimizations which were applied
+- target_nodes.txt: a file describing the different nodes in the VM graph
+
+Attaching the artifact with your issue or Slack message may help people to have a look at the core of the problem.
+The more precise your bug, the more likely we can reproduce and fix
+
+[TODO: Umut, is it still needed or do we already have some of those information in artifacts?]
+In order to simplify our work and let us reproduce your bug easily, any information is useful. Notably, in addition to the python script, some information like
+- the OS version
+- the python version
+- the python packages you use
+- the reproducibility rate you see on your side
+- any insight you might have on the bug
+- any workaround you have been able to find
+may be useful to us. Don't remember, Concrete is a project where we are open to contribution, more information at Contributing (TODO: add a link).
+
+## Submitting an issue
+
+In case you have a bug, which is reproducible, that you have reduced to a small piece of code,  we have our issue tracker (TODO: LINK TO BE ADDED). Remember that a well-described short issue is an issue which is more likely to be studied and fixed. The more issues we receive, the better the product will be.   

docs/user/howto/FAQ.md

@@ -1,3 +1,14 @@
 # FAQ
 
-to be done
+## What is Concrete FHE?
+
+See [here](../../README.md)
+
+## Is it an open source project?
+
+## Can I use it freely?
+
+## Can I contribute?
+
+## What are the future features of Concrete?
+

docs/user/howto/REDUCE_NEEDED_PRECISION.md

@@ -1 +1,3 @@
 # Having a Function Which Requires Less Precision
+
+Arthur to do: #319

docs/user/howto/SUBMIT_ISSUE.md

@@ -1 +0,0 @@
-# Submitting Issues

docs/user/howto/SUPPORT.md

@@ -1 +0,0 @@
-# Support

docs/user/tutorial/FIRST_TUTORIAL.md

@@ -1,3 +1,5 @@
 # First Tutorial
 
-To be continued
+Umut to do: #312
+
+

docs/user/tutorial/SECOND_TUTORIAL.md

@@ -1,3 +1,3 @@
 # Second Tutorial
 
-To be continued
+Umut to do: #313

docs/user/tutorial/THIRD_TUTORIAL.md

@@ -1,3 +1,3 @@
 # Third Tutorial
 
-To be continued
+Umut to do: #314