improve doc

README.md

@@ -205,7 +205,7 @@ Checkout the [library](/backend/library/libraries/) and [tools](/tools/) for the
 
 A library can be a framework, a catalog of threats or reference controls, and even a custom risk matrix.
 
-Take a look at the `tools` directory and its dedicated readme. The `convert_library.py` script will help you create your library from a simple Excel file. Once you have structured your items in that format, just run the script and use the resulting yaml file.
+Take a look at the `tools` directory and its [dedicated README](tools/README.md). The `convert_library.py` script will help you create your library from a simple Excel file. Once you have structured your items in that format, just run the script and use the resulting yaml file.
 
 You can also find some specific converters in the tools directory (e.g. for CIS or CCM Controls).
 

tools/README.md

@@ -6,6 +6,8 @@ Have a look to the given examples.
 
 ## Usage
 
+Usage: python convert_library [--compat] your_library_file.xlsx
+
 To launch it, open a shell in a command line, and type:
 
 ```bash
@@ -14,6 +16,8 @@ python convert_library.py your_library_file.xlsx
 
 This will produce a file name your_library_file.yaml
 
+The compat flag is recommended only to maintain libraries that have been generated prior or up to release 1.9.20. Without the compat flag, URNs generated for nodes without ref_id are constructed using the parent_urn. These generated URNs are much simpler to understand and maintain if required, compared to the previus system using "nodeXXX" suffix.
+
 ## Format of Excel files
 
 ```
@@ -57,13 +61,9 @@ Conventions:
         tab                             | <tab_name> | implementation_groups
         tab                             | <tab_name> | risk_matrix
         tab                             | <tab_name> | mappings
+        tab                             | <tab_name> | answers
 
-    
-    For libraries:
-        - library_provider is the entity that provides the reference document (e.g. ANSSI, NIST). 
-        - library_packager is the entity that converts the reference document in a library for CISO Assistant (e.g. intuitem). the value "intuitem" for packager is reserved for intuitem. Other packagers are kindly asked to use another descriptive value.
-        - library_description shall be sufficiently detailed, and shall contain a link to the reference document.
-        - framework_ref_id, framework_name and framework_description are generally identical to their corresponding values for library.
+        variables can also have a translation in the form "variable[locale]"
 
     For requirements:
         If no section_name is given, no upper group is defined, else an upper group (depth 0) with the section name is used.
@@ -78,6 +78,8 @@ Conventions:
             - reference_controls
             - annotation
             - typical_evidence
+            - questions
+            - answer
             - skip_count: trick for fixing a referential without changing the urns (advanced users)
         The normal tree order shall be respected
         If multiple threats or reference_control are given for a requirements, they shall be separated by blank or comma.
@@ -87,7 +89,7 @@ Conventions:
             - ref_id(*)
             - name
             - description
-            - category (policy/process/techncial/physical).
+            - category (policy/process/technical/physical).
             - csf_function (govern/identify/protect/detect/respond/recover).
             - annotation
     For risk matrices:
@@ -108,8 +110,14 @@ Conventions:
             - relationship(*)
             - rationale
             - stregth_of_relationship
-    A library has a single locale. Translated libraries have the same urns, they are merged during import.
+    For Answers:
+        The first line is a header, with the following possible fields (* for required):
+            - id(*)
+            - question_type(*)
+            - question_choices(*)
+    A library has a single locale, which is the reference language. Translations are given in columns with header like "name[fr]"
     Dependencies are given as a comma or blank separated list of urns.
+
 ```
 
 ## Mappings

tools/convert_library.py

@@ -1,5 +1,11 @@
 """
 simple script to transform an Excel file to a yaml library for CISO assistant
+Usage: python convert_library [--compat] your_excel_file
+
+The compat flag is recommended only to maintain libraries that have been generated prior or up to release 1.9.20.
+Without the compat flag, URNs generated for nodes without ref_id are constructed using the parent_urn.
+This generated urns that are much simpler to understand and maintain if required.
+
 Conventions:
     | means a cell separation, <> means empty cell
     The first tab shall be named "library_content" and contain the description of the library in the other tabs