On 05/12/2015 05:22 AM, Thierry Carrez wrote: > John Garbutt wrote: >> On 11 May 2015 at 23:46, Boris Pavlovic <bo...@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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
