Docs: comment on cc notebook

3 files changed, 29 insertions, 11 deletions

diff --git a/docs/index.md b/docs/index.md
index 61c39ec5..4760ed1c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,7 +2,7 @@
 
 Welcome to the technical documentation of *sec-certs* tool for the data analysis of products certified with Common Criteria or FIPS 140 frameworks. If you're looking for general description of the tool, its use cases and capabilites, we refer you to [sec-certs homepage](https://seccerts.org/). If you are looking for more advanced knowledge, e.g. how to mine your own data, how to extend the tool, and so forth, this is the right place.
 
-There are three main parts of this documentation. *User's guide* describes high-level use of our tool. Driven by this knowledge, you can progress to *Notebook examples* that showcase most of the API that we use in the form of Jupyter notebooks. The documentation currently does not have all modules documented with `autodoc`, so for the API reference, you must directly inspect the [sec_certs](https://github.com/crocs-muni/sec-certs/tree/main/sec_certs) module. If you want, you can run the notebooks as they are stored in the [project repository](https://github.com/crocs-muni/sec-certs/tree/main/notebooks). If you are interested in contributing to our project or in other aspects of our development, you can consult the relevant *GitHub artifacts*
+There are three main parts of this documentation. *User's guide* describes high-level use of our tool. Driven by this knowledge, you can progress to *Notebook examples* that showcase some of the API that we use in the form of Jupyter notebooks. The documentation also contains some of the modules documented with `autodoc`, see *API reference*. Still, some dark corners of our codebase are not documented. To inspect the code directly, see the [sec_certs](https://github.com/crocs-muni/sec-certs/tree/main/sec_certs) module. If you want, you can run the notebooks as they are stored in the [project repository](https://github.com/crocs-muni/sec-certs/tree/main/notebooks). If you are interested in contributing to our project or in other aspects of our development, you can consult the relevant *GitHub artifacts*
 
 ```{button-ref} quickstart
 :align: center
diff --git a/docs/tutorial.md b/docs/tutorial.md
deleted file mode 100644
index 47e78870..00000000
--- a/docs/tutorial.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Tutorial
-
-TBA
\ No newline at end of file
diff --git a/notebooks/examples/common_criteria.ipynb b/notebooks/examples/common_criteria.ipynb
index 83a56379..677dcd28 100644
--- a/notebooks/examples/common_criteria.ipynb
+++ b/notebooks/examples/common_criteria.ipynb
@@ -6,7 +6,9 @@
    "source": [
     "# Common Criteria example\n",
     "\n",
-    "This notebook illustrates basic functionality with the `CCDataset` class that holds Common Criteria dataset and of its sample `CommonCriteriaCert`"
+    "This notebook illustrates basic functionality with the `CCDataset` class that holds Common Criteria dataset and of its sample `CommonCriteriaCert`.\n",
+    "\n",
+    "Note that there exists a front end to this functionality at [seccerts.org/cc](https://seccerts.org/cc/). Before reinventing the wheel, it's good idea to check our web. Maybe you don't even need to run the code, but just use our web instead. "
    ]
   },
   {
@@ -24,7 +26,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Get fresh dataset snapshot from mirror"
+    "## Get fresh dataset snapshot from mirror\n",
+    "\n",
+    "There's no need to do full processing of the dataset by yourself, unless you modified `sec-certs` code. You can simply fetch the processed version from the web. \n",
+    "\n",
+    "Note, however, that you won't be able to access the `pdf` and `txt` files of the certificates. You can only get the data that we extracted from it. \n",
+    "\n",
+    "Running the whole pipeline can get you the `pdf` and `txt` data. You can see how to do that in the last cell of this notebook."
    ]
   },
   {
@@ -41,7 +49,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Do some basic dataset serialization"
+    "## Do some basic dataset serialization\n",
+    "\n",
+    "The dataset can be saved/loaded into/from `json`. Also, the dataset can be converted into a [pandas](https://pandas.pydata.org/) DataFrame. "
    ]
   },
   {
@@ -58,7 +68,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -70,7 +80,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Simple dataset manipulation"
+    "## Simple dataset manipulation\n",
+    "\n",
+    "The certificates of the dataset are stored in a dictionary that maps certificate's primary key (we call it `dgst`) to the `CommonCriteriaCert` object. The primary key of the certificate is simply a hash of the attributes that make the certificate unique.\n",
+    "\n",
+    "You can iterate over the dataset which is handy when selecting some subset of certificates."
    ]
   },
   {
@@ -112,7 +126,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Dissect single certificate"
+    "## Dissect single certificate\n",
+    "\n",
+    "The `CommonCriteriaCert` is basically a data structure that holds all the data we keep about a certificate. Other classes (`CCDataset` or `model` package members) are used to transform and process the certificates. You can see all its attributes at [API docs](https://seccerts.org/docs/api/sample.html)."
    ]
   },
   {
@@ -134,6 +150,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Select all certificates from a dataset for which we detect at least one vulnerability.\n",
     "vulnerable_certs = [x for x in dset if x.heuristics.related_cves]"
    ]
   },
@@ -141,7 +158,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Serialize single certificate"
+    "## Serialize single certificate\n",
+    "\n",
+    "Again, a certificate can be (de)serialized into/from json. It's also possible to construct pandas `Series` from a certificate as shown below"
    ]
   },
   {
@@ -185,6 +204,8 @@
    "source": [
     "## Create new dataset and fully process it\n",
     "\n",
+    "The following piece of code roughly corresponds to `$ cc-certs all` CLI command -- it fully processes the CC pipeline. This will create a folder in current working directory where the outputs will be stored. \n",
+    "\n",
     "*Warning*: It's not good idea to run this from notebook. It may take several hours to finnish. We recommend using `from_web_latest()` or turning this into a Python script."
    ]
   },