Wednesday, 22 September 2010

PostgreSQL docs reloaded

If you regularly reference the online PostgreSQL docs, you may have noticed that they have just had a face-lift in time for the big 9.0 release. If not, take a look. This went through quite a few revisions with input from many folk in the Postgres community. As with all things, you won't please everyone, and this is no less true in the case of this redesign. But look at this as a pilot change, where we've come up with a first version with possible "bug-fixes" to follow. I've also provided similar changes for the French version, although there's only been feedback from one person for that. Regardless, they appear to have gone with it anyway.

I'm no designer, and neither are the majority of the people who contributed their recommendations, but the original cause of me wanting to make some changes is so that the examples which appear throughout the docs would be distinct from the main body text. Previously they appeared to all merge into one which made it difficult to pick out the various elements on the page. This involved simple indentation, but I thought that while I was there, I'd get rid of the horrible default borders on the tables, and then show warnings in a red box, and notes in beige... etc.. etc.

So now I'm soliciting feedback. I firmly believe that PostgreSQL seriously has some of the best documentation out there; clear, comprehensive and organised. So design changes mustn't be distracting, should aid readability and help communicate. Is it confusing? Does it make you want to cry?.. with joy.. with pain?

17 comments:

Screwtape said...

I expect it will be many years before PostgreSQL 9.0 winds up in RHEL and I wind up having to consult the docs to find something out, so I haven't looked too closely - but at first glance, the updated styles look gorgeous.

Way to go!

Colin said...

I've just jumped ship from the Oracle world. I think I arrived post-update. Whatever the case: the documentation is great and easy to read. Comprehensive also, where the Oracle documentation often isn't, instead being just verbose.

KJ said...

Nice update! Clean and easy to read.

Also great that a cut-and-paste of code blocks still doesn't grab unwanted characters either or otherwise mangle code like some other sites.

Bob said...

The docs looks awesome! Nice job!

Steve said...

Looks great in Firefox, not so great in Safari.

Thom said...

Safari not displaying okay? What aspect doesn't look right?

We tested this in Safari (Windows and OSX) and also various versions of OmniWeb, Camino, Opera, Firefox, Chrome, Chromium, Konqueror, IE6, IE8.

Grzegorz J said...

very solid. Me likes it.
As for the Safari, I dunno. Firefox and Chrome seem to be happy on linux. Will check on safari at home.

roppert said...

Noticed the docs were easier to read now. Thanks for that!

Florence said...

I like it a lot.
It is nice, and still clear and simple (not too shiny for me)
I like the French version, too. And as one of the translators, it was for me a good surprise.
Thank you for your work.

Richard Broersma said...

To me, the presentation of tables are by far the biggest improvement. And I'm speaking just in terms of readability.

Steve said...

@Thom I think Safari was caching the old CSS. I hit reload and it looks good now. Good work.

Bruce Momjian said...

Screwtape: The new layout affects all versions of the documentation, not just PG 9.0.

Andreas Karlsson said...

The new style is nice expect for being a bit too strong. A smaller corner radius and a shorter shadow would probably make it more discrete and still good looking and legible.

My suggestions are border radius 6 and 1 or 2 pixels shorter shadow. 8 pixels radius is quite alot.

Thom said...

Hi Andreas.

Thanks for the suggestion. There were probably a few things we could have changed before going live, but at the time we decided to go with what we had because we'd never get it finished. But I tend to agree that the corners could be made a tad more subtle. I'll try your suggestion on the next round of changes.

Gurjeet said...

Overall, great work.

I think the blueish colour for table header-background and the borders isn't fitting well with the rest of the page. Maybe I'll start liking it in a few days, but over the past few days that colour always felt like out of place.

Maybe a shade of grey would keep it in line with the rest of the page.

Also, if we are at it, can we make it skinnable? Like depesz.com's Wordpress themes are choosable (bottom of the right panel)

Just my 2 cents.

Andreas Karlsson said...

Thom, I agree with that way of working. Better to have something good done than never getting anything done in the search for the perfect.

Andreas said...

One thing I'm missing over the years: The upper navigation ("Prev", "Fast Backward", "Fast Forward", "Next") does not contain the "Up" option which is offered in the lower navigation area. I find myself always scrolling down, pressing "Up", ...

*PLEASE* fix this! :-)