Re: Images in the official documentation

On 27 February 2018 at 03:23, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Craig Ringer <craig(at)2ndquadrant(dot)com> writes:
> > On 26 February 2018 at 12:16, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> >> How can we resolve these issues?
>
> > Question the assumptions and requirements. Why do we actually _need_
> > diffable, mergeable images? Sure, it'd be *nice*, but what's the real
> world
> > impact if we don't have it?
>
> Well, I'll tell you exactly why I'm being sticky about this: we've been
> down this road before. We used to have some figures in .gif format,
> and one of the problems with them was they were too hard to update.
> I don't buy the "they won't need updates" argument for a second, either.
> For instance, I recall that one of the images we had was a diagram of
> the system catalog cross-references, and it was constantly out of date
> because of the difficulty of updating it.
>

Yeah, that sounds painful. I can certainly see your objection when framed
in terms of things like illustrations of catalogs and catalog relationships.

If I were maintaining the docs in a vacuum, I'd use graphviz for something
like that, because it's a figure that does need regular updates and
changes. And because
the list of fun things to do in my life definitely does not include
hand-writing SVG. Not that tweaking GraphViz .dot is fun, but it's the
default tool for a reason.

I'd be awfully tempted to generate the node-map part of the catalog
relationship .dot file from a query, too.

I still advocate for relaxing the policy for images that are *not* likely
to need frequent updates, but also for being conservative about how/when we
include images. Does this add real value to the docs, is it worth any
maintenance hassle? Then, for things that will change more, like catalogs,
using a tool like graphviz. If we object to adding a docs build-dependency,
we could always commit generated files like we already do for the
'configure' script, and make sure there's a committer/maintainer Make
target that warns if the sources are newer than the docs.

--
Craig Ringer http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services