New Website design #2517
Replies: 26 comments 70 replies
-
|
Hi, here is the link for the accepted GSOC project for the website. Please check this Figma link to the user interface I recommend. Its homepage needs more content in between. I would like to know the homepage requirements so that I can improve or redesign this page (if it doesn't look good). Also, I would like to change the UI for other pages as well if needed. |
Beta Was this translation helpful? Give feedback.
-
|
I wonder if we want to add a version selector or something like that to the documentation. |
Beta Was this translation helpful? Give feedback.
-
|
ok if I understand your idea correctly. We have to show documentation for all released versions.
|
Beta Was this translation helpful? Give feedback.
-
|
Yeah, something like that. Or something like |
Beta Was this translation helpful? Give feedback.
-
|
Okay, I will modify Figma to accommodate these changes & is there any suggestion for other pages? |
Beta Was this translation helpful? Give feedback.
-
|
I wanted to confirm if we need a version selector on our site as it has to be created with a side menu, otherwise adding it in the future becomes complicated considering how Hugo works. |
Beta Was this translation helpful? Give feedback.
-
|
I like the idea, but let's refer to @davecramer for a decision. |
Beta Was this translation helpful? Give feedback.
-
|
that's an interesting idea. |
Beta Was this translation helpful? Give feedback.
-
|
Did you mean to show all download links in other formats instead of a table? |
Beta Was this translation helpful? Give feedback.
-
|
I mean only show downloads for a specific version. Currently we carry way too much history in downloads |
Beta Was this translation helpful? Give feedback.
-
|
@davecramer which versions should I remove from tables? |
Beta Was this translation helpful? Give feedback.
-
|
I like the idea of having 3 (or maybe up to 5 versions) directly visible. And then everything else behind an extra link. |
Beta Was this translation helpful? Give feedback.
-
|
last 3 are fine. we need to keep the most recent 42.2.x version |
Beta Was this translation helpful? Give feedback.
-
|
Other ideas that have come up have been to use hugo instead of jekyll as hugo does not have any dependencies |
Beta Was this translation helpful? Give feedback.
-
|
Alternative option: https://twitter.com/dps/status/1524409067761848320, https://markdoc.io/ |
Beta Was this translation helpful? Give feedback.
-
|
as does this |
Beta Was this translation helpful? Give feedback.
-
|
Well, both Hugo has the fastest build time among other good SSGs. Markdoc's integration with React & Next is interesting. |
Beta Was this translation helpful? Give feedback.
-
|
Here's another idea: apply https://diataxis.fr/ |
Beta Was this translation helpful? Give feedback.
-
|
This looks interesting |
Beta Was this translation helpful? Give feedback.
-
|
That's a very nice looking site... |
Beta Was this translation helpful? Give feedback.
-
|
Which framework is decided for the website? |
Beta Was this translation helpful? Give feedback.
-
|
I also think |
Beta Was this translation helpful? Give feedback.
-
|
Unless there is a specific need for another SSG, then |
Beta Was this translation helpful? Give feedback.
-
|
hello, @vlsi @bokken @sehrope please share your framework choice for the new website. |
Beta Was this translation helpful? Give feedback.
-
|
@jorsol , I've never used and seen Hugo before. Do you have a sample of a ~similar site to see what it might look like? I see that Hugo favours "single binary" and "website build performance". I just checked Hugo samples, and the syntax for if/when/etc looks weird. Well, it does look like an alien language to me :-/ I would rather value
On the other hand, I have no experience with Hugo and markdoc, so I would listen what others say. I would be OK to move off Jekyll, as I did experience issues with installing Jekyll, and I would like to avoid installing/launching Docker just for the sake of building a website. |
Beta Was this translation helpful? Give feedback.
-
|
Well, Hugo has live preview, the templating is Liquid (Jekyll) vs. Go templating (Hugo), and maybe is a little bit easier to learn Jekyll’s syntax than Hugo’s, yet I don't see it as a blocker, it's just a matter of get use to it, at first the Jekyll syntax was odd to me (and still does), and even then if the site is pretty much "complete" to add normal content it just markdown. As for a sample site you could look at https://learn.netlify.app/en/ that is a ready to use theme for Hugo, to see a real world example check https://kubernetes.io/docs/home/ The latest version of Hugo has improved the error reporting since v0.99.0+ versions (very recently actually), yet if we are limited with some distro package version I might suspect it won't be a big deal. The site/documentation should be more or less complete and might not need to touch the templating, right now what is touched most of the time in the current site is the markdown content, so unless a special feature is needed, the templating should not be a concern IMHO. For the JS-based solutions, I don't really have any opinion, and they could serve well for our purpose, yet as far I can tell it also requires node/npm dependencies to be installed, and that's the single point that makes me favor Hugo even without the build performance. |
Beta Was this translation helpful? Give feedback.
-
|
+1 to hugo for site generation. Ideally the site shouldn't even require any JavaScript either. Just a boring static site with a nice file structure, can be indexed by a search engine, and linked to externally (ex: /path/to/connection-props.html#some-prop). Not sure how that would play with having historical versions available. Maybe we publish the generated site to a separate archive site or subdir? I have no specific opinions on CSS or layout frameworks. Anything that's easy to use with wide browser support is fine, ideally with minimal customizations. And any dependencies should be vendored rather than externally linked. I'm not sure how to describe it in words, but I'd much rather have something like the old server docs than something like the new ones: Old docs (good): https://www.postgresql.org/docs/9.5/functions-json.html New docs (bad): https://www.postgresql.org/docs/14/functions-json.html I think the changes there were something to do with getting a responsive layout that works on mobile. IMHO, it makes the tables very difficult to read on a desktop which is the primary use case for this kind of site. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for giving your opinion on this.I understood what you said. In the new version of the document, the columns are removed and all the data in the previous column is combined into one column, which makes it difficult to read. The main focus of a website should be a good user experience, not a good user interface. I think most members agree on this point. |
Beta Was this translation helpful? Give feedback.
-
|
Here's an idea how to generate a client-side search in Hugo: |
Beta Was this translation helpful? Give feedback.
-
|
So talking to the postgres infrastructure guys we would be limited to hugo that is available on debian so currently on the server we have version 0.55.6+really0.54.0-1. and this should be upgraded to 0.80.0-6 As for optimizing for mobile I agree that we should not be too concerned with that as this is a document and reading it on a mobile would not be the target audience. I am willing to be proven wrong though. |
Beta Was this translation helpful? Give feedback.
-
|
We will be setting Github actions, So we are limited to the version here. In Hugo, the advanced features can be helpful to make code more organized and reusable. The latest version currently supported by Debian was released in 2020. Since then, Hugo has made many improvements and bug fixes. |
Beta Was this translation helpful? Give feedback.
-
|
Maybe we can find some old approaches on StackOverflow. But the problem with their documentation is that it doesn't contain any information about the approach of older versions. |
Beta Was this translation helpful? Give feedback.
-
|
This can also be used the other way around: GH Actions runs on a recent Ubuntu version and builds the website from Markdown. Then everyone benefits from the newer versions. |
Beta Was this translation helpful? Give feedback.
-
|
Then we have to download their latest binary to use the latest version on our OS. |
Beta Was this translation helpful? Give feedback.
-
Currently we are limited to what is available on Debian as that is what the host jdbc.postgresql.org runs on. We could change that but I'd rather not unless there is a good reason. |
Beta Was this translation helpful? Give feedback.
-
|
Well my informal twitter survey suggests people do read docs on their phone, mostly when they don't have access to a computer. In some cases in companies where networks are not allowed, or while commuting |
Beta Was this translation helpful? Give feedback.
-
|
I plan to make the website as responsive as possible without interfering with the user experience on a wide browser screen. |
Beta Was this translation helpful? Give feedback.
-
|
Hi, @vlsi on a Heisenbug conference told me that pjdbc is in the process of changing site. I see a great work has been done. Probably my considerations will be of some help. I would choose not from general SSG solutions like Jekyll, Hugo, 11ty etc., but from SSG solutions for documentation. Most popular products here are Antora and Sphinx. Among markdown solutions, the most popular is probably Docusaurus. My pick would be Antora. It is very mature solution with the richest ecosystem (if compared to other mentioned products), still very simple to start with. Besides, I have a feeling that Antora/Asciidoctor sites are most popular for documentation of open source products. Antora is well in line with the GSOC proposals, there are out-of-the-box solutions for versioning, industrially accepted default UI (great both on desktop and mobile devices), very good IDE support, the greatest documentation and very helpful community. Instead of Markdown it uses Asciidoc (Asciidoc is a language, Asciidoctor is its compiler inside Antora) but it is the same easy and much more standardized and mature. At least there will be no bulky tr/td tags in tables. Markdown can be more or less easily converted to Asciidoc. Considerations (IMHO) regarding GSOC project itself and discussion:
|
Beta Was this translation helpful? Give feedback.
-
|
I'm intrigued by this. It seems to me that using a framework that is specifically designed for documentation makes sense. I'm sure there are things that they know that we don't. Anyone else have opinions here ? |
Beta Was this translation helpful? Give feedback.
-
@davecramer & @andreasscherbaum your thoughts on this? |
Beta Was this translation helpful? Give feedback.
-
|
not exactly sure what the author means here. AFAICT they need to be managed by hand for the most part. There is no github automation that automatically manages release notes |
Beta Was this translation helpful? Give feedback.
-
|
Well, I think that he is referring to using the the "Releases" feature from GitHub, and even the release notes can be autogenerated by GitHub, this is mostly extracting the PRs titles between the previous tag and release tag. Just to test it I created a release for 42.4.0 that can be seen here: https://github.com/pgjdbc/pgjdbc/releases Anyway, the release notes could still be managed by hand and just keep in sync with the CHANGELOG.md file. Now, I think the point here is to publish the release notes also on the website or only on the Releases of GH. |
Beta Was this translation helpful? Give feedback.
-
|
Hello, @everyone The Figma design that I shared above was lacking some content in its middle causing a disbalance in the visual hierarchy. So I have thought of some content that we can add. Please verify this wireframe. Also please let me know if anything else is required to add here.
|
Beta Was this translation helpful? Give feedback.
-
|
Overall, I like the content included in this design - having prominent Download and Documentation links are going to be important to any visitors. It does seem a little tall/narrow. If you did want to make it a bit wider (beneficial so users don't have to scroll down for more content), you could slide the Why Pgjdbc/Latest Releases content into a vertical pane (a column wide) on the right, and have the Features/Processing a Simple Query/etc other content (basically the space of 2 or 2-1/2 columns wide) in the main body. |
Beta Was this translation helpful? Give feedback.
-
|
We need to move forward, so in the absence of any dissenting opinions lets decide on using hugo for site generation |
Beta Was this translation helpful? Give feedback.
-
|
Hi, @everyone. I have started writing code for our new website. As decided I am using the GitHub actions testing repo - https://github.com/utkar-sh-ukla/testing |
Beta Was this translation helpful? Give feedback.
-
|
Raised PR for these changes #2555 |
Beta Was this translation helpful? Give feedback.
-
|
We need to organize the content title of the doc. Some pages' title is very long while some have very short text. I am thinking of creating a two-level side nav which is generally used. We will show the subtopics card on the right side when someone chooses any particular topic. like in this page |
Beta Was this translation helpful? Give feedback.
-
|
Yes, I like that. I'm curious how much realestate that is going to take up on a mobile |
Beta Was this translation helpful? Give feedback.
-
|
Hi. https://postgis.net/ just make so sense. I especially like documentation section. |
Beta Was this translation helpful? Give feedback.
-
|
Well, the documentation section on this website is precisely similar to what we have had on our current website. |
Beta Was this translation helpful? Give feedback.
-
|
this https://www.psycopg.org/psycopg3/docs/basic/install.html is pretty clean |
Beta Was this translation helpful? Give feedback.
-
|
This website looks pretty nice. |
Beta Was this translation helpful? Give feedback.
-
|
I think the psycopg docs look better than their website - the website doesn't resize well. One thing that is distracting about the website is the empty space to the left and right of the main content (while the menu has slid off to the far left). You can really see that emptiness (and missing menu) when it opens on a large monitor. |
Beta Was this translation helpful? Give feedback.
-
|
Hi, also share your opinion on this homepage |
Beta Was this translation helpful? Give feedback.
-
|
Overall, I think it's an attractive layout, but some of the white space is a little too big - specifically, between the sections/around the puzzle graphic. Also, I wonder about the differences in the font size used for the different types of content. The font used at the page end is a lot bigger than the font used in the navigation headings, and I would usually rather have bigger (easier) navigation headings, and smaller end-of-page content. I do think it's a good starting point though! |
Beta Was this translation helpful? Give feedback.
-
|
Yeah, you are right font-weight balance is not right in some places. |
Beta Was this translation helpful? Give feedback.
-
|
Did you make progress with the new website? |
Beta Was this translation helpful? Give feedback.
-
|
Hi please check the current progress https://utkar-sh-ukla.github.io/testing/ The content is not responsive yet. |
Beta Was this translation helpful? Give feedback.
-
|
I have created a new repository for this work https://github.com/pgjdbc/pgjdbcdocs |
Beta Was this translation helpful? Give feedback.
-
|
Why moving document sources? I guess it would require having extra PRs for docs. |
Beta Was this translation helpful? Give feedback.
-
|
I thought you had asked for this to avoid people having to download extra files for these PR's ? |
Beta Was this translation helpful? Give feedback.
-
|
I suggest we keep documentation sources in the main repository (so we can edit side by side with code), and we push the compiled HTML to a different repository as we do with compiled classes. |
Beta Was this translation helpful? Give feedback.
-
|
Ya, I re-read that. So ya we can do that although I'm not sure how to get github to automatically publish them? |
Beta Was this translation helpful? Give feedback.
-
|
Having this in a different repo lets him work on his own. I'm indifferent |
Beta Was this translation helpful? Give feedback.
-
|
You already have GitHub Actions and can use that to trigger publish to a GitHub page (or any other host). |
Beta Was this translation helpful? Give feedback.
-
|
@everyone Please give your feedback on the current progress https://pgjdbc.github.io/pgjdbc/. |
Beta Was this translation helpful? Give feedback.
-
|
What do you think of using JetBrains Mono font for monospace cases? Frankly speaking, I wonder if the number of various font sizes can be reduced.
It looks small or hard to read at this size (I'm on 16" retina mac with default scaling).
I'm inlined we do not need
We would probably want to hyperlink version number, not a generic
The titles are underscored, so they look like hyperlinks to be. Do you intend to make them clickable? If not, what do you think of removing the underline then? |
Beta Was this translation helpful? Give feedback.
-
Great Idea I will try this font for monospace cases.
Yes, the text is a bit difficult to read in paragraphs. Will try to find the solution for this.
okay, I will do it.
I copied this design from the official Postgres website. Your opinion is valid but when the user will hover over Note then it will look different from other notes text and the user will not have trouble finding the version.
No, I just added them for design Purposes. will remove them because they may confuse users. Thanks for sharing your valuable opinions! |
Beta Was this translation helpful? Give feedback.
-
|
@vlsi I have made all the changes you suggested, please check https://pgjdbc.github.io/pgjdbc/ |
Beta Was this translation helpful? Give feedback.
-
|
Hi Guys! The website is starting to really come together nicely! Can I suggest closing up the vertical whitespace literally about a row - when the font is a comfortable size for my eye, there is just a little too much white space between topics. What I'm using as a gauge is that the space above the Why Pgjdbc? heading is almost as big as the content below it, and the same for the Java icon below that. Also, we need to use one capitalization for PgJDBC - I've seen it spelled: pgjdbc, pgJDBC, Pgjdbc and PgJDBC. |
Beta Was this translation helpful? Give feedback.
-
|
Hi, Any suggestions on current progress? Is there any additional functionality you would like to see on the site? For large screens, the website is complete, all that remains is to make it responsive for other screens. |
Beta Was this translation helpful? Give feedback.
-
|
Looks good to me! |
Beta Was this translation helpful? Give feedback.
-
|
I really like how the new design comes together. Just a few small things I spotted (not sure if all are part of GSoC):
Good work overall! |
Beta Was this translation helpful? Give feedback.
-
|
great feedback, thanks for reviewing |
Beta Was this translation helpful? Give feedback.
-
|
@andreasscherbaum Thank you so much for your feedback! I will look into all the issues you mentioned |
Beta Was this translation helpful? Give feedback.
-
|
Here is the latest https://pgjdbc.github.io/pgjdbc/ |
Beta Was this translation helpful? Give feedback.
-
|
Is there a summary as of what was changed over the last two weeks? |
Beta Was this translation helpful? Give feedback.
-
|
The site has been made responsive and we added a changelogs link to show the changelogs |
Beta Was this translation helpful? Give feedback.
-
|
All in all it looks good on my mobile (Android), I checked yesterday already The Changelogs has the same breadcrumb problem: the main Changelogs page shows the link in blue, but once you click on an entry the blue highlight is gone. |
Beta Was this translation helpful? Give feedback.
-
|
I'm not following the last bit. What blue highlight do you want to persist? |
Beta Was this translation helpful? Give feedback.
-
|
When you click on "https://pgjdbc.github.io/pgjdbc/changelogs/", the "Changelogs" link is blue highlighted. |
Beta Was this translation helpful? Give feedback.
-
|
Hmm good catch it's actually consistent with other pages as well. For instance |
Beta Was this translation helpful? Give feedback.
-
|
Yes, that's what I wrote here. |
Beta Was this translation helpful? Give feedback.
-
|
Got it! will try to find some solution for this issue. |
Beta Was this translation helpful? Give feedback.
-
|
I just realized all the documentation files are in |
Beta Was this translation helpful? Give feedback.
-
|
this is the default format for hugo. What is the issue with html? |
Beta Was this translation helpful? Give feedback.
-
We have a GSoC project approved for creating a new website.
I'd like to have ideas presented here.
A couple things I would like to see is a more modern website.
Possibly automated deployment.
Beta Was this translation helpful? Give feedback.
All reactions