Re: Documentation and explanatory diagrams

On Sun, Jul 11, 2010 at 11:32 AM, Steve Atkins <steve(at)blighty(dot)com> 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