On 12/05/15 09:57, Joe Gordon wrote: > When learning about how a project works one of the first things I look > for is a brief architecture description along with a diagram. For most > OpenStack projects, all I can find is a bunch of random third party > slides and diagrams. > > Most Individual OpenStack projects have either no architecture diagram > or ascii art. Searching for 'OpenStack X architecture' where X is any > of the OpenStack projects turns up pretty sad results. For example > heat [0] an Keystone [1] have no diagram. Nova on the other hand does > have a diagram, but its ascii art [2]. I don't think ascii art makes > for great user facing documentation (for any kind of user). > > So how can we do better then ascii art architecture diagrams? > How about ascii source diagrams? > [0] http://docs.openstack.org/developer/heat/architecture.html > [1] http://docs.openstack.org/developer/keystone/architecture.html > [2] http://docs.openstack.org/developer/nova/devref/architecture.html > These are all sphinx generated documents, so we could use something like blockdiag to generate all manner of diagrams https://pypi.python.org/pypi/sphinxcontrib-blockdiag http://blockdiag.com/en/