handle-docs: add more details about book.yml workflow

Change-Id: I47fb5bedf6d1e70c0f5e2607bf67b3947b210b1c
Signed-off-by: Sebastien Douheret <sebastien.douheret@iot.bzh>

2 files changed, 49 insertions, 27 deletions

diff --git a/docs/handle-docs/simple-book.yml b/docs/handle-docs/book.yml.in
index ebee034..52e8eb7 100644
--- a/docs/handle-docs/simple-book.yml
+++ b/docs/handle-docs/book.yml.in
@@ -4,8 +4,8 @@ books:
     id:
     order:  #optional
     title:
-    title_fr: #optionnal
-    title_jp: #optionnal
+    title_fr: #optional
+    title_jp: #optional
     description:
     keywords:
     author:
@@ -37,8 +37,8 @@ books:
     id:
     order:  #optional
     title:
-    title_fr: #optionnal
-    title_jp: #optionnal
+    title_fr: #optional
+    title_jp: #optional
     description:
     keywords:
     author:
diff --git a/docs/handle-docs/handle-docs.md b/docs/handle-docs/handle-docs.md
index 9f3c522..c0ade95 100644
--- a/docs/handle-docs/handle-docs.md
+++ b/docs/handle-docs/handle-docs.md
@@ -1,28 +1,45 @@
-# How to add markdown files to AGL documentation
+# Abstract
+
+AGL doc website is based on a collection of markdown files fetched from various repositories.
+A tool available in [docs-tools](https://github.com/automotive-grade-linux/docs-tools) takes
+care of collecting and templating all markdown files according fetched_files.yml located in
+[docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate).
+
+<!-- TODO add SCHEMA + description of fetched_files.yml and book.yml logic -->
+
+## How to add a new documentation section into AGL documentation
 
-This documentation helps you to add new markdown files to AGL documentation.
 They are two steps to add new markdown files to AGL documentation:
 
-- Add a book yaml file to the repository where the markdown files are.
-- Add an entry into the section yaml file that point to your book file. The section yaml file is in docs-webtemplate repository (git@github.com:automotive-grade-linux/docs-webtemplate.git) named ```section_<version>.yml```.
+- Add a book yaml file to the repository where the documentation sources are located (written in markdown files).
+- Add an entry into the global section yaml file that point to your book file. The section yaml file is in [docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate) repository (`git@github.com:automotive-grade-linux/docs-webtemplate.git`) named `section_<version>.yml`.
 
 ---
 
-**Note**: To generate a local documentation please refer to the README of the docs-webtemplate (https://github.com/automotive-grade-linux/docs-webtemplate) and use the script ```setupdocs.sh```.
+**Note**: To generate a local documentation please refer to the [README](https://github.com/automotive-grade-linux/docs-webtemplate/blob/master-next/README.md) of the docs-webtemplate (https://github.com/automotive-grade-linux/docs-webtemplate) and use `setupdocs.sh` script.
 
 ---
 
-## Add a book yaml file into repository
+### Add a book yaml file into a repository
+
+The book file is needed to describe how your documentation is structured and must be used to describe
+among others :
+
+- the global title of the doc
+- the chapter name when the doc will be part of the whole documentation website
+- subchapters list and consequently subchapters hierarchy
+- multi-language description
+
+<!-- TODO: Add more explanation of multi-language support (eg. suffix xxx_en, xxx_jp ) -->
 
-The book file is needed to describe your documentation.
 There are several types of book:
 
 - book
 - api
 
-### Book Type
+#### Book Type
 
-The book type describes documentation chapters.
+`book` type describes documentation structure and chapters.
 Below the generic way to include a book file:
 
 ```yaml
@@ -30,7 +47,8 @@ type: books
 books:
 -
     id: <ID1>
-    order: x #optional: between 0 in 100 default is 50, it allows to define order in final          #documentation, more the order number is low more the documentation is first
+    order: x #optional: between 0 in 100 default when not set is 50, it allows to define order in final
+             #documentation, more the order number is low more the documentation is first
     title: title of your chapter  #default title
     title_<lang>: title in <lang>
     description: description of your book
@@ -40,17 +58,17 @@ books:
     chapters:
         - name: Name of your subchapter
           name_<lang>: Name of your subchapter in <lang>
-            url: "%lang%/softlink/to/your/mardown.md" #%lang% will be replaced by the
-                                                      #available languages,
-                                                      #default language can be in the root directory
+            url: "%lang%/relative-path/to/your/mardown.md" #%lang% will be replaced by the
+                                                           #available languages,
+                                                           #default language can be in the root directory
         - name: Name of your subchapter
           name_<lang>: Name of your subchapter in <lang>
-          url: "%lang%/softlink/to/your/mardown.md"
+          url: "%lang%/relative-path/to/your/mardown.md"
         - name: Name of your subchapter
           name_<lang>: Name of your subchapter in <lang>
             - name: Name of your subsubchapter
               name_<lang>: Name of your subsubchapter in <lang>
-              url: "%lang%/softlink/to/your/mardown.md"
+              url: "%lang%/relative-path/to/your/mardown.md"
             - name: Name of your subsubchapter
               name_<lang>: Name of your subsubchapter in <lang>
               children:
@@ -62,21 +80,25 @@ books:
     ...
 ```
 
-Here a simple yaml file, you can start from :
+[book.yml.in](https://github.com/automotive-grade-linux/docs-sources/blob/master/docs/handle-docs/book.yml.in)
+is a sort of schema of book.yml. This file contains all supported keys.
+
+Here a sample yaml file, you can start from :
 
 ```bash
-wget https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/handle-docs/simple-book.yml
+wget https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master-next/docs/getting-started-book.yml -O my-new-book.yml
 ```
 
-### Api Type
+#### Api Type
 
 In progress
 
-## Add an entry in section file
+### Add an entry in section file
 
 There are 4 sections in docs: getting_started, architecture_guides, developer_guides, apis_services.
 
-They are located in content/docs in docs-webtemplate repository. In addition, each directory contains several section yaml file, one a version. For master version, it is ```section_master.yml```.
+They are located in `content/docs` in [docs-webtemplate](https://github.com/automotive-grade-linux/docs-webtemplate) repository.
+In addition, each directory contains several section yaml file, one a version. For master version, it is `section_master.yml`.
 
 Below the structure of section yaml file.
 
@@ -91,14 +113,14 @@ books:
     id: <ID1>
     url_fetch: <url_fetch> #optional, overload the default one
     git_commit: <git_commit> #optional, overload the default one
-    path: "softpath/from/root/repository/to/the/book/yaml/file"
+    path: "relativepath/from/root/repository/to/the/book/yaml/file"
     books: #optional: subbooks, will be a child of the above book
         - id: <SUBID2>
           url_fetch: <url_fetch> #optional, overload the default one
           git_commit: <git_commit> #optional, overload the default one
-          path: "softpath/from/root/repository/to/the/book/yaml/file"
+          path: "relativepath/from/root/repository/to/the/book/yaml/file"
         - ...
 -
     id: <ID2>
     ...
-```
\ No newline at end of file
+```