In ironic, we have use asciiflow several times quite successfully in the spec process.
We also maintain in-tree docs with .PNG graphics, and versioning those has been a bit of a pain. They were originally taken out of slide decks, and served their purpose, but really ought to be in a different format or a different tree now. -D On May 12, 2015 2:15 AM, "John Garbutt" <[email protected]> wrote: > On 11 May 2015 at 23:46, Boris Pavlovic <[email protected]> wrote: > >> Couldn't we just use real image files to do this. IIRC, gerrit supports > >> displaying image files which are included in a commit. For example, I've > >> been > >> planning to copy these images: > > > > +1 for real images > > One suggestion I remember around specs was we might want a separate > repo to contain the images, to stop massively increasing the git clone > times. > > In the spec template we recommend this to generate diagrams: > http://asciiflow.com/ > > See: > http://specs.openstack.org/openstack/nova-specs/specs/liberty/template.html > > Thanks, > John > > > On Tue, May 12, 2015 at 1:36 AM, Matthew Treinish <[email protected]> > > wrote: > >> > >> On Mon, May 11, 2015 at 02:57:48PM -0700, 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? > >> > > >> > [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 > >> > >> Couldn't we just use real image files to do this. IIRC, gerrit supports > >> displaying image files which are included in a commit. For example, I've > >> been > >> planning to copy these images: > >> > >> https://wiki.openstack.org/wiki/QA/AuthInterface > >> > >> into the tempest docs for some time. They just need to be updated a bit > to > >> reflect some recent changes. > >> > >> The only downside I see is that it makes editing more difficult, I guess > >> that's > >> really the tradeoff. > >> > >> -Matt Treinish > >> > >> > __________________________________________________________________________ > >> OpenStack Development Mailing List (not for usage questions) > >> Unsubscribe: > [email protected]?subject:unsubscribe > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > >> > > > > > > > __________________________________________________________________________ > > OpenStack Development Mailing List (not for usage questions) > > Unsubscribe: > [email protected]?subject:unsubscribe > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: [email protected]?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
