Open Stack

Sean Dague wrote:
> On 05/12/2015 05:22 AM, Thierry Carrez wrote:
>> John Garbutt wrote:
>>> On 11 May 2015 at 23:46, Boris Pavlovic<boris at pavlovic.me>  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.
>
> PNG / SVG files pack down pretty well in git repos. But this might be a
> good case for submodules if people think things are actually getting out
> of hand on space.
>
>> Also like Matt mentioned, images can't be easily modified. As time
>> passes by, that usually results in stale information as people don't go
>> through the hassle of completely redoing the image to update the
>> information in it. That makes them fine for shiny one-time
>> presentations, but inadequate for long-term technical docs.
>>
>> For those I really prefer to optimize for accuracy than for prettiness,
>> so ascii art, or blockdiag, or anything we can easily share the source
>> of, is to be preferred to raw images.
>
> ascii art gives you 2 dimensions to convey information. A real image
> gives you a ton more (color, boldness, fonts, fine grained white space
> control, layers, crossing but non intersecting lines). The density of
> information presented in a proper diagram goes beyond ascii art by a
> couple of orders of magnitude.
>
> They can be modified if you provide source files, or use a source
> oriented format like SVG, or ISO standard ODG (used by OpenOffice /
> LibreOffice). There is a reason the "spider" diagram has ended up in
> every single OpenStack presentation I've seen for the last 2 years.
>
> Personally, ascii art doesn't click. They are usually trivially simple
> and didn't need to exist (oh, 2 things and a connector, why did someone
> bother to diagram that?), or complicated enough that it now takes real
> mental energy to figure out what's going on (oh... so starred lines are
> a different thing, wait, that / line is important too?). A diagram that
> takes more time to decypher than the paragraph describing it.
>
> I mean try doing this workflow in ascii art -
> http://docs.openstack.org/infra/manual/developers.html and see if it's
> as clear.
>
> We write things down to communicate, with people that aren't ourselves.
> Maybe there is a subset of humanity where ascii art is a clarifying
> wonder. I would argue it's a small subset, even in our community. So
> lets err on the side of communicating effectively in documentation with
> people that aren't just us.
>

+1 to all of this,

I've tried to make sure taskflow has all these grounds covered and it 
still saddens me that we don't have that many other diagrams elsewhere 
that help newbs (and experienced folks...). I'd almost rather have *any* 
format vs. no diagrams in the end...

Some can be/are automatically generated from actual code...

- http://docs.openstack.org/developer/taskflow/states.html
- http://docs.openstack.org/developer/ironic/dev/states.html

> 	-Sean
>