Open Stack

Hi,

I have looked through the Admin Guide and have made the following
observations. This is intended to be constructive criticism, and in no
way a condemnation of the guide as it exists today.

Here are my findings:

* A lot of the diagrams use different styles

* Ordering issues

  * A lot of topics in the scenarios (like provider
  networking) are discussed before the actual sections that introduce
  what the API extension does. It may be worth moving some sections
  around.
  
  * Some topic changes are abrupt - Jumps straight from an intro, into
  sections about the LBaaS and FwaaS offerings. It may be difficult to
  follow because there is very little about how Neutron actually
  "works" in-between those two sections

* Section on placing services on physical hosts has no diagrams. It
  would probably be helpful to have a diagram that shows physical
  connectivity, then a diagram showing logical connectivity. There are
  a couple diagrams like this that I've seen on presentations and
  other documentation.

* Networking scenarios for OVS could be improved
	* Provider networking scenario is really detailed, very good

	* VXLAN example is very short - only shows the edge nodes

* Linux Bridge is very similar to OVS scenario. Is it possible to consolidate? Perhaps it is worth documenting the differences between LinuxBridge and OVS to help guide plugin selection?

* ML2 network scenario only discusses L2 population driver. May need
  to have documentation explaining that the ML2 plugin can use the
  same scenarios as LinuxBridge and OVS?

* Admin Guide has a section on HA - is it the same as the High
  Availablilty Guide? Or is it another way to do HA?

* Section about plug-in pagination and sorting is a stub

* Large sections on proprietary plugin configurations - fate of this
  section depends on the fate of proprietary plugins in the Neutron
  tree.


Overall the Admin Guide has a tough job. In my mind, the purpose of
the Admin Guide is to give operators enough information to configure
Neutron, while also introducing them to the architecture and how
Neutron works under the covers, so that when a problem is encountered
they can diagnose and fix. In addition, knowing some of the internals
of Neutron will help explain what all the configuration parameters
actually do.

-- 
Sean M. Collins