From: Bruce Momjian <bruce@momjian.us>
Message-Id: <201009132132.o8DLWWj04402@momjian.us>
Subject: Re: [DOCS] Doc fixes and improvements
In-Reply-To: <4C8E2454020000250003560D@gw.wicourts.gov>
To: Kevin Grittner <Kevin.Grittner@wicourts.gov>
Date: Mon, 13 Sep 2010 17:32:32 -0400 (EDT)
CC: Peter Eisentraut <peter_e@gmx.net>, Thom Brown <thom@linux.com>,
	Magnus Hagander <magnus@hagander.net>,
	PostgreSQL www <pgsql-www@postgresql.org>, Tom Lane <tgl@sss.pgh.pa.us>
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset="US-ASCII"

Kevin Grittner wrote:
> Peter Eisentraut <peter_e@gmx.net> wrote:
>  
> > There are just too many things going on.  Reduce the number of
> > colors, reduce the number of different border designs (round, not
> > round), make the borders less busy (remove the line), remove the
> > shadows, reduce the number of different levels of indentation.
>  
> Personally, I would be disappointed if we backed off from these
> changes much.  The current docs look like something I would have
> seen coming off the bidirectional print-head of a Teletype(R)
> machine a few decades ago.  I've gone back and forth between that

Agreed.

> and Thom's latest draft trying to pick out useful information on
> various pages, and for me the visual cues help considerably in
> finding what I want.  On top of that, switching to the new look is a
> refreshing experience each time; when I switch back to our current
> docs, I can actually feel my eyes tighten up as they prepare to pick
> out content from a mass of uniform text.
>  
> I know people process visual information differently, but I really
> have a hard time seeing anything offensive about where Thom has
> taken it, and that was based on a lot of feedback from several
> different people.

Agreed.

FYI, everyone should be looking at the same version:

	http://pgweb.darkixion.com:8081/docs/8.4/static/sql-syntax-lexical.html

If we make these changes, there is nothing in stone preventing us from
tweaking it later, but I think there is general agreement that the new
format is an improvement. We have to accept we will never make everyone
happy.

The only constructive suggestion I can make to perhaps make more people
happy would be to go with only vertical lines to highlight the code
blocks, e.g. instead of:

	+-------------+
	|  text       |
	+-------------+

we do
	
	|  text       |

but I am not sure if I even would prefer that.

FYI, I would like to see this rolled into our production web server in
the next few days so it is ready for the 9.0 release.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +