Re: Documentation and explanatory diagrams

On Jul 16, 2010, at 7:20 PM, Robert Haas wrote:

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

You're misunderstanding.

My suggestion is to use a standard format, rather than a
proprietary format. A standard format can be edited by a
range of different tools, on different platforms. A proprietary
format can only be edited by a single tool (and single tools
that support multiple platforms tend to be mediocre).

Having our VCS containing, as one example, solely SVG
as a vector format, and allowing people to use any image
editor they want to to edit or create that format is
what I'm talking about.

(There are some issues - with diffs and suchlike - with
using multiple tools to edit a single format, but I suspect
they're fairly minor compared to the benefits of using a
standard, documented, open format.)

> 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,

So lets not pick a tool. Lets use a portable format.

> (b) we will be stuck with it for a very long time, and

So lets pick a simple, widely supported format, so we're not
stuck with one particular tool and it's format, and we can
migrate the content to a new, widely supported format easily
if the issue comes up.

> (c) the
> source files that the tool uses will need to be managed by a version
> control system.

And lets pick a format that's at least moderately text-based and
diff-friendly.

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

If the end result is crap, or the working files are not maintainable
then that's a bad thing for the project. That's true if the working files are
C source code and the end result is an executable or if the working
files are <some random vector format> and the end result is a
graphic in the docs.

My feeling is that SVG is a decent lowest common denominator. It's
not *great*, but it's very widely supported and can be generated or
edited by pretty much any tool, and can be rendered to PDF or PNG
by standard tools without too much effort (other than careful choice
of fonts in the original format).

I'm not gung-ho about this - if someone comes up with another
great way to generate diagrams, I'm all for it. But choosing a
proprietary format that's only supported by a single tool, and
that renders to horrible quality PNGs is something we'll regret,
I think.

Cheers,
Steve