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 <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.
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. __________________________________________________________________________ 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