Open Stack

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?

Thanks,
John