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?

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!
9/22/2010 1:36 pm
Colin 't Hart 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.
9/22/2010 1:40 pm
KJ said…
This comment has been removed by the author.
9/22/2010 2:18 pm
Unknown said…
The docs looks awesome! Nice job!
9/22/2010 3:03 pm
Steve said…
Looks great in Firefox, not so great in Safari.
9/22/2010 3:52 pm
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.
9/22/2010 3:57 pm
Greg Jaskiewicz 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.
9/22/2010 5:17 pm
roppert said…
Noticed the docs were easier to read now. Thanks for that!
9/22/2010 5:25 pm
Unknown 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.
9/22/2010 5:29 pm
Richard Broersma said…
To me, the presentation of tables are by far the biggest improvement. And I'm speaking just in terms of readability.
9/22/2010 6:30 pm
Steve said…
@Thom I think Safari was caching the old CSS. I hit reload and it looks good now. Good work.
9/22/2010 9:52 pm
Bruce Momjian said…
Screwtape: The new layout affects all versions of the documentation, not just PG 9.0.
9/22/2010 10:18 pm
Unknown 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.
9/22/2010 11:09 pm
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.
9/23/2010 7:51 am
Gurjeet Singh 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.
9/23/2010 8:03 am
Unknown 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.
9/23/2010 9:24 am
Unknown 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! :-)
9/23/2010 5:33 pm
Post a Comment

Popular posts from this blog

Deprecated features in PostgreSQL - Past to present

If you have been using PostgreSQL for a long time, or you’re relatively new but have been following old instructions about how to use it, it’s possible that you’re using features that have been deprecated. The reason features disappear tend to be because they have been superseded by better features which cover the same functionality. It’s important to try to avoid using features which are destined to disappear if there’s a newer alternative. Also when planning an upgrade, it’s useful to know if a feature you’re using will suddenly break in the new version. Some of these features still continue to work, but have since been removed from documentation because they’re to be removed in a future release. Others have just been removed completely. We’ll start off with the absurdly old and work our way to the present: Version 6.2 timetravel contrib module Does it still work?: No. This is ooooold and was last supported back in PostgreSQL 6.1. What’s wrong with it?: This really dragged p...
Read more

jsquery vs SQL/JSON

SQL/JSON is coming to PostgreSQL 12 and provides a native way to query JSON data (although, to be specific, JSON data stored as a JSONB data type).  This also introduces the jsonpath data type which is used for SQL/JSON query expressions.  I'll not be going into its usage in detail, or covering performance characteristics (at least not in this post), but I will compare the syntax and functionality with jsquery.  Note that this may potentially change prior to final release. jsquery was introduced as a non-core extension for PostgreSQL 9.4 and higher by Teodor Sigaev, Alexander Korotkov and Oleg Bartunov.  Like jsonpath, it also used its own datatype, jsquery. We have some functions to which we can pass jsonpath expressions to, 2 of which have operators which can be used as shorthand (albeit without additional parameter control, as they exist primarily for indexing purposes): Function Operator Description jsonb_path_exists ...
Read more

PostgreSQL 9.6 - Part 2 - Monitoring

This is part 2 in a 4 part blog series on improvements coming in PostgreSQL 9.6. Part 1 - Horizontal Scalability Join Pushdown Sort Pushdown "Walk and chew gum at the same time" Part 2 - Monitoring VACUUM progress monitoring Wait monitoring Part 3 - Parallelism Part 4 - Vertical Scalability VACUUM progress monitoring When you run VACUUM on a large table, do you know how much it's done after 5 minutes? Do you know how much more there is to go? The answer is, no. You can't know, at least not accurately or easily. In PostgreSQL 9.6, you'll be able to monitor just this (although not VACUUM FULL), thanks to the work of Amit Langote (NTT) and Robert Haas (EnterpriseDB), which was built upon the work done by Rahila Syed (EnterpriseDB) and Vinayak Pokale (NTT). We now have a system view called pg_stat_progress_vacuum. This is the first in, hopefully, several progress monitoring views to come in future. Here's an example of what it shows you (shown in...
Read more