public inbox for [email protected]  

help / color / mirror / Atom feed

From: Robert Haas <[email protected]>
To: Steve Atkins <[email protected]>
Cc: pgsql-docs <[email protected]>
Subject: Re: Documentation and explanatory diagrams
Date: Fri, 16 Jul 2010 22:20:26 -0400
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
	<[email protected]>
	<[email protected]>

On Sun, Jul 11, 2010 at 11:32 AM, Steve Atkins <[email protected]> wrote:
> I have no dog in this fight, and I'd be overjoyed to see diagrams of
> any sort. I do think that requiring use of a single, fairly clunky, graphics
> package rather than allowing people who get the urge to create a
> diagram to use whichever graphics program they're familiar with is
> likely to lead to more, and better, documentation.

Unless I'm misunderstanding what you're talking about here, this is a
really, really bad idea.  If we let people use whatever editor they
want to generate diagrams, we'll be unable to easily modify those
diagrams when needed.  If our version control system contains a
mixture of dia, xfig, Adobe illustrator, etc, etc source files it'll
be a nightmare.

I think it's important to keep in mind here that (a) whatever tool we
pick will become a requirement either for everyone who wants to build
the docs, or at a minimum for those people who want to work with the
images, (b) we will be stuck with it for a very long time, and (c) the
source files that the tool uses will need to be managed by a version
control system.  The version control system and the patch files that
we email around are the lifeblood of this project.  Any thought that
the quality or quantity of diagrams is more important than how well a
particular system plays with our version control system is, IMHO, 100%
backwards.  I spent more time using git, cvs, and related tools than I
do any other utility on the system, with the possible exception of vi.
 I suspect many other developers are in the same boat, modulo
s/vi/$EDITOR/.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company

view thread (114+ 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]
  Subject: Re: Documentation and explanatory diagrams
  In-Reply-To: <[email protected]>

* 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