On 12/05/15 06:48 -0400, 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 <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 imagesOne 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.
Not much to add other than I'm with Sean here. Also, Joshua proposed using Dia. I've used it and it works well for these cases. Cheers, Flavio
-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
-- @flaper87 Flavio Percoco
pgp5IaDQVfRrX.pgp
Description: PGP signature
__________________________________________________________________________ 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
