[openstack-dev] [nova][all] Architecture Diagrams in ascii art?

Joe Gordon joe.gordon0 at gmail.com
Fri May 15 21:27:09 UTC 2015


On Thu, May 14, 2015 at 3:52 AM, John Garbutt <john at johngarbutt.com> wrote:

> On 12 May 2015 at 20:33, Sean Dague <sean at dague.net> wrote:
> > On 05/12/2015 01:12 PM, Jeremy Stanley wrote:
> >> On 2015-05-12 10:04:11 -0700 (-0700), Clint Byrum wrote:
> >>> It's a nice up side. However, as others have pointed out, it's only
> >>> capable of displaying the most basic pieces of the architecture.
> >>>
> >>> For higher level views with more components, I don't think ASCII art
> >>> can provide enough bandwidth to help as much as a vector diagram.
> >>
> >> Of course, simply a reminder that just because you have one or two
> >> complex diagram callouts in a document doesn't mean it's necessary
> >> to also go back and replace your simpler ASCII art diagrams with
> >> unintelligible (without rendering) SVG or Postscript or whatever.
> >> Doing so pointlessly alienates at least some fraction of readers.
> >
> > Sure, it's all about trade offs.
> >
> > But I believe that statement implicitly assumes that ascii art diagrams
> > do not alienate some fraction of readers. And I think that's a bad
> > assumption.
> >
> > If we all feel alienated every time anyone does anything that's not
> > exactly the way we would have done it, it's time to give up and pack it
> > in. :) This thread specifically mentioned source based image formats
> > that were internationally adopted open standards (w3c SVG, ISO ODG) that
> > have free software editors that exist in Windows, Mac, and Linux
> > (Inkscape and Open/LibreOffice).
>
> Some great points make here.
>
> Lets try decide something, and move forward here.
>
> Key requirements seem to be:
> * we need something that gives us readable diagrams
> * if its not easy to edit, it will go stale
> * ideally needs to be source based, so it lives happily inside git
> * needs to integrate into our sphinx pipeline
> * ideally have an opensource editor for that format (import and
> export), for most platforms
>
> ascii art fails on many of these, but its always a trade off.
>
> Possible way forward:
> * lets avoid merging large hard to edit bitmap style images
> * nova-core reviewers can apply their judgement on merging source based
> formats
> * however it *must* render correctly in the generated html (see result
> of docs CI job)
>
> Trying out SVG, and possibly blockdiag, seem like the front runners.
> I don't think we will get consensus without trying them, so lets do that.
>
> Will that approach work?
>
>
Sounds like a great plan.


> Thanks,
> John
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150515/47e40f21/attachment.html>


More information about the OpenStack-dev mailing list