Open Stack

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.

	-Sean

-- 
Sean Dague
http://dague.net