Documentation issues

[Ron Wheeler <rw...@artifact-software.com>]

There are some simple problems with the documentation.
Some of these have been raised in the past but never fixed.

http://docs.cloudstack.apache.org/en/latest/concepts.html  is the first 
technical page that a new user will read.

*Loose text.*

At the top of the page under Concepts and Terminology there is a 
sentence that looks out of place.
"Primary storage is associated with a cluster"

*DIAGRAMS too simple and possibly wrong
*

The diagrams for Zones, Pods,Clusters should show at least 2 of the next 
lower level. The diagram for Regions looks much clearer as it show 3 
zones that make up the Region. The Pod diagram looks like the Primary 
storage is inside the Cluster which is different from what the text 
says. "A pod consists of one or more clusters of hosts and one or more 
primary storage servers"

*Clusters must have identical hardware*

The text says "The hosts in a cluster all have identical hardware, run 
the same hypervisor, are on the same subnet, and access the same shared 
primary storage." Is it true that the hardware must be "identical".That 
seems to an overstatement of the requirement.

*Redundant t**ext**in Cluster*

This sentence should be removed. It is clear from the whole discussion 
of the hierarchy.
"A cluster is the fourth-largest organizational unit within a CloudStack 
deployment. Clusters are contained within pods, and pods are contained 
within zones."

*Cluster Size*
" Size of the cluster is limited by the underlying hypervisor, although 
the CloudStack recommends less in most cases; see Best Practices."

What doe this actually mean? Is it true? Would an example make it clearer?
The hyperlink to Best Practices is missing.

*Host question*

The description says

  * May reside in multiple data centers across different geographic location

This contradicts previous statements that hosts exist inside clusters 
which are inside pods and zones which can only be in one datacenter.
This section also says that host in a cluster must be homogeneous which 
is different from identical but in no place is either identical or 
homogeneous ever defined and these are not commonly used in Computer 
Science with the definitions which I think are meant here.
*
**Primary Storage section contradicts Pod definitions and the entire 
previous hierachy*
The Pod section says that a pod consists of clusters and primary 
storage.  This section says that Primary storage is "associated" with a 
cluster not a pod.
It then goes on to recommend that Primary storage should be at the Zone 
level.
  Can someone make up a consistent definition of the relationship of 
Primary Storage to the rest of the structures and fix the diagrams to 
match the actual reality.

*Redundant Network Traffic Type definitions*
Not sure why the definitions are associated with both Basic and Advanced 
Network Traffic Types. The definitions appear to be the same and the 
fact that they appear twice is confusing.

*Basic Zone Network Traffic Type only requires Guest Network**
*The description of Basic Zone Network configuration says that you only 
need to define a Guest network. It makes no comments about the other 
traffic types.

*Accounts and Customers never defined*
In the discussion about Advanced Zone Guest IP Addresses, the concept of 
Accounts is used with no definition of what accounts.
There is also a mention of "Customers" without any description of what 
"Customers" means in a Cloudstack context.
*
**General Comment on exceptions
*My personal view is that there are too many references to specific 
product exceptions. These add too many confusing and conflicting**ideas 
for an introductory article. This is supposed to be  an introduction to 
the concepts and terminology that will be used in the rest of the 
documentation.*
*

-- 
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102