Open Stack

On 05/14/2015 06:52 AM, John Garbutt 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 great to me. This is all about being pragmatic.

	-Sean

-- 
Sean Dague
http://dague.net