Open Stack

Excerpts from Sean Dague's message of 2015-05-12 03:48:11 -0700:
> 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.

I agree with all the things above, and I want to add that I think SVG
is probably the most appropriate candidate as a W3C approved drawing
format. We can even enforce style rules and use a reformatter so that
diffs make sense.

Pictures are important, and we need more of them in our docs.