update intro

Signed-off-by: maxwolfs <[email protected]>

Author: maxwolfs

docs/intro.md

@@ -16,27 +16,25 @@ The aim of this documentation is to give operators, cloud service provides and o
 
 ## Structure
 
-In order to get all the different docs into one place and to render a comprehensive static page for best Developer Epxerience, the subprojects need to be consumed by this main docs repository. This is will be managed by git's subtree feature and not as submodule. TODO: Why?
+### Conceptual Structure
 
-[The Power of Git Subtree by Nicola Paolucci](https://blog.developer.atlassian.com/the-power-of-git-subtree/?_ga=2-71978451-1385799339-1568044055-1068396449-1567112770)
+We follow the [Diataxis Framework](https://diataxis.fr/) to structure our documentation, in order respond best to our users needs.
 
-```bash
-git subtree add --prefix {local directory being pulled into} {remote repo URL} {remote branch} --squash
-```
+### Directory Structure
 
-## Implications to subtree repositories structure
+In order to get all the different docs into one place and to render a comprehensive static page for best Developer Epxerience, the subprojects need to be consumed by this main docs repository. This is will be managed by git's subtree feature and not as submodule.
 
-As the final output in this repository will be a statically generated website, the subtree docs repositories should only contain markdown and static files for visualisation.
+As the final output in this repository will be a statically generated website, the subtree docs repositories should only contain markdown and static files. If a sub repository should reside within a repository which code it is documenting, it should also be imported as subtree or submodule. This is a bit more management overhead, but also enbables the freedom of choice for rendering the content in another output repository as a static page with any docs renderer. But furthermore this enables this SCS Docs repository to inherit all the different docs rendered into one page for the best user experience.
 
-## Directory Structure
+#### SCS project repo strucutre
 
 ```jsx
 project
 ├── static  // static content
 ├── blog    // optional blog
 ├── src     // source files
 ├── docs    // the folder where all individual docs reside as subtree modules
-│   └── @osism/openstack-image-manager
+│   └── @osism/openstack-image-manager-docs
 │       ├── overiew.md
 │       ├── usage.md
 │       ├── requirements.md
@@ -60,3 +58,39 @@ project
 .       .
 .          .
 ```
+
+```jsx
+@osism/openstack-image-manager
+├── code  // static content
+├── blog    // optional blog
+├── src     // source files
+├── docs    // the folder where all individual docs reside as subtree modules
+│   └── @osism/openstack-image-manager-docs
+│       ├── overiew.md
+│       ├── usage.md
+│       ├── requirements.md
+│       ├── images
+│       │   ├── logo.png
+│       │   └── image.svg
+│       └── support
+│           ├── index.js
+│           └── styles.module.css
+```
+
+### Git subtree
+
+[The Power of Git Subtree by Nicola Paolucci](https://blog.developer.atlassian.com/the-power-of-git-subtree/?_ga=2-71978451-1385799339-1568044055-1068396449-1567112770)
+
+[Git Subtree Basics Gist](https://gist.github.com/SKempin/b7857a6ff6bddb05717cc17a44091202)
+
+In order to add a docs repository we use the following git commmand:
+
+```bash
+git subtree add --prefix /docs/{repo name} {remote repo URL} {remote branch} --squash
+```
+
+For updating the repo we use the following git commmand:
+
+```bash
+git subtree pull --prefix /docs/{repo name} {remote repo URL} {remote branch} --squash
+```