document the colour coding and other doc facilities

History.txt

@@ -1,6 +1,6 @@
 # 1.1.0
  * Added task to create a graph of all available tasks as documentation (with colors)
-  * Using [Brewer scheme Set 1 of 9-class](http://colorbrewer2.org/#type=qualitative&scheme=Set1&n=9) for colours. Unfortunately no color-blind safe option for 9 classes available
+  * Using [ColorBrewer Set 1 of 9-class](http://colorbrewer2.org/#type=qualitative&scheme=Set1&n=9) for colours. Unfortunately no color-blind safe option for 9 classes available
 
 # 1.0.0
  * Major restructure.

README.md

@@ -20,21 +20,17 @@ Gaudi is meant to be a part of you code repository from the initial commit. To t
 
 Install the gaudi gem:
 
-```
-gem install gaudi
-```
+```gem install gaudi```
 
 Create the project scaffold:
 
-```
-gaudi -s gaudi_project
-```
+```gaudi -s gaudi_project```
+
+This will create a basic project structure and pull the current version of gaudi from the repo. The scaffold also adds the correct files and structure to support features like the [documentaiton tasks](doc/DOCUMENTATION.md)
 
 Add the gaudi-c module:
 
-```
-gaudi -l gaudi-c https://github.com/damphyr/gaudi.git gaudi_project
-```
+```gaudi -l gaudi-c https://github.com/damphyr/gaudi.git gaudi_project```
 
 ## Gaudi?
 
@@ -46,7 +42,7 @@ Gaudi was very much a builder and a craftsman, each of his buildings unique yet
 
 (The MIT License)
 
-Copyright (c) 2013-2017 Vassilis Rizopoulos
+Copyright (c) 2013-2018 Vassilis Rizopoulos
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

doc/BUILDSYSTEMS.md

@@ -24,7 +24,7 @@ It is meant to provide a consistent command line interface to every task and ope
 
 The underlying principles for such a system are [described elsewhere](ASPIRATIONS.md)
 
-The areas of responsibility for such a system can be categorized with labels like "build", "test", "deploy" but this becomes much easier if we color code it and add some pictures:
+The areas of responsibility for such a system can be categorized with labels like "build", "test", "deploy" but this becomes much easier if we colour code it and add some pictures:
 
 ![Areas of Responsibility](/doc/images/BuildSystem.png)
 

doc/DOCUMENTATION.md

@@ -0,0 +1,38 @@
+# gaudi documentation features
+
+## Gaudi library documentation
+
+```rake doc:gaudi```
+
+Since rake and gaudi is Ruby code there is a built-in facility for generating RDoc documentation.
+
+The `doc:gaudi` task will automatically generate the reference documentation for the build system code under `system_config.out/doc/gaudi`.
+
+It uses doc/BUILDSYSTEM.md as the main page, a file that is created when using the gaudi gem to scaffold a project.
+
+
+## Graphs
+
+Gaudi is meant to cover all responsibility areas of an extended build system (as [explained elsewhere](BUILDSYSTEMS.md)).
+
+![Areas of Responsibility](/doc/images/BuildSystem.png)
+
+On a mature system the number of tasks can quickly become overwhelming. To manage it better gaudi provides a task to create graphs (using the [graphviz dot format](http://www.graphviz.org/doc/info/lang.html) and the [graph](https://github.com/seattlerb/graph) gem)
+
+Use ```rake doc:graph:gaudi``` to create the diagram (as `system_config.out/doc/graphs/gaudi.png`).
+
+One organizational measure is to group tasks by namespace. If you use the following responsibility-to-namespace mapping you will get colours in the generated graph matching the colours in the overview image.
+
+|Area|Namespace|
+|----|----|
+|Generate|gen|
+|Build|build|
+|Static Analysis|lint|
+|Unit Testing|unit|
+|Package|pkg|
+|Deployment|deploy|
+|Test|test|
+
+In addition the `doc` namespace is assigned the brown variant in the colour scheme
+
+The colour pallete used is [Brewer scheme Set 1 of 9-class](http://colourbrewer2.org/#type=qualitative&scheme=Set1&n=9)