Re: Docs refreshed

From: Thomas Lockhart <lockhart(at)alumni(dot)caltech(dot)edu>
To: Peter Eisentraut <peter_e(at)gmx(dot)net>
Cc: Postgres Hackers List <hackers(at)postgresql(dot)org>
Subject: Re: Docs refreshed
Date: 2000-04-03 01:21:22
Message-ID: 38E7F212.D32BE3FB@alumni.caltech.edu
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

> > Just as you, I assume that people using html read the integrated doc.
> Btw., the fact that the print docs are in US Letter format makes them
> slightly beyond useless for the rest of the world. :( I still think that a
> 200 page document is not any less unwieldy than a 600 page one. There's
> gotta be an option to only print pages x through y either way.

<bad attitude>
Hmm. I'm glad you appreciate the hundreds of hours of work I've put
into the docs :/ And I haven't seen anyone else stepping up to
providing hardcopy-style docs for "the rest of the world". And I
personally value hardcopy docs any time I try to learn something (as
opposed to just refreshing my memory on a detail) and think that it is
important for others too.
</bad attitude>

> Considering that this is pretty much what's holding up releases, would it
> be possible to consider not putting the postscript docs in the
> distribution and just put them on the ftp server at your convenience (and
> in A4 as well) for those who choose to get it? Not to break your heart or
> something but thinking practically ... :)

OK, there is a little known secret here: the docs are *not* holding up
the release. But, the release will be held up until both docs *and*
the release are ready to go, and at the moment neither are. In fact, a
fundamental part of our release cycle is that, for the last couple of
weeks before the actual release, the project is "waiting for docs",
and during that time, the old adage that "idle hands do the devil's
work" comes into play and people start poking at the release, trying
things, putting it into production, maybe, trying it on all platforms,
etc etc, and we find a few extra bugs and get our platform reports
finalized. And all of this is essential for a quality release. So
don't believe the docs story too much, but don't try doing away with
the sham either ;)

btw, I hadn't fully realized the above until you started poking at it,
so thanks :)

> Also don't put them in the CVS tree. They're just wasting space since
> they're out of date and not really useful for developers.

You haven't yet suggested enough other mechanisms to adequately
replace the current scheme, but I'll do it for you, under separate
cover sometime soon.

> In the same spirit I'd suggest not including the html tars in the CVS tree
> either. In the distribution I would like to have them *untarred* so users
> can browse them before/without installing. But for that they can be
> generated when making the distribution (make -C doc postgres.html, not too
> hard but we'd need to use a separate build dir), no need to keep out of
> date copies in CVS.

Well, the copies *aren't* out of date for the corresponding release
version, so that isn't the issue afaict. tar vs untar doesn't seem to
be a big issue either, though the tarball is pretty much required if
the html is in cvs since the names of the html files only occasionally
reproduce from one rev to the next (note the large number of random
generic names for internal portions of chapters).

- Thomas

--
Thomas Lockhart lockhart(at)alumni(dot)caltech(dot)edu
South Pasadena, California

In response to

Browse pgsql-hackers by date

  From Date Subject
Next Message Tom Lane 2000-04-03 05:32:20 Re: 7.0 release notes should call out incompatible changes more clearly
Previous Message Ryan Kirkpatrick 2000-04-03 00:35:24 Re: Call for porting reports