public inbox for [email protected]  

help / color / mirror / Atom feed

From: Craig Ringer <[email protected]>
To: Tom Lane <[email protected]>
Cc: Steve Atkins <[email protected]>
Cc: [email protected]
Subject: Re: Images in the official documentation
Date: Tue, 27 Feb 2018 09:02:40 +0800
Message-ID: <CAMsr+YG0uD2j9ZzSQJrRCNcDCsrWA4MG9Fns-bj3QWEr-8A5UQ@mail.gmail.com> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
	<[email protected]>
	<[email protected]>
	<CAMsr+YEfh3qgxDeyAThi-nv0k3ptxhOZKW44kKzcaspGnWzC2A@mail.gmail.com>
	<[email protected]>
	<CAMsr+YGE8PU4THTTEXk4YkbfkZQrU32JJYojJzhQaKkZUKfXAQ@mail.gmail.com>
	<[email protected]>

On 27 February 2018 at 03:23, Tom Lane <[email protected]> wrote:

> Craig Ringer <[email protected]> writes:
> > On 26 February 2018 at 12:16, Tom Lane <[email protected]> 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

view thread (23+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected], [email protected]
  Subject: Re: Images in the official documentation
  In-Reply-To: <CAMsr+YG0uD2j9ZzSQJrRCNcDCsrWA4MG9Fns-bj3QWEr-8A5UQ@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox