Update to docs root pages and navigation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
24 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Update to docs root pages and navigation

Magnus Hagander-2
I think it requires a silly number of steps to get to our
documentation today. It's not huge, but it's "click documentation,
click "current manuals", click 13". And the actual /docs/ page is
mostly empty, which makes it a waste.

PFA a patch that changes this:

* The /docs/ page now gets direct links to all supported documentation
versions, including PDFs

* The /docs/ page gets a big button that sends you directly to
/docs/current/ -- that link wasn't  available at all before

* Translated manuals were listed both on the left and right sidebar on
the root docs page, but not on the manuals page. Remove them from the
left sidebar, leave them on the right one since it's now on the root
docs page.

Unrelated to the restructuring, but while at it:
* Make the left column in the manuals table not take 50% of the width
when all it has is a number

* Add a link to the developer docs

* Remove the repetitive "comprehensive manual" text (it's no more
comprehensive than the other manual, it's just a different format),
and insert a proper separator between the two PDF versions

* Remove some redundant and incorrect template tags probably resulting
from previous copy/paste mistakes

I'm also attaching a screenshot of the main docs page with the
changes, for those that can't easily test a website patch. (Nevermind
the actual versions listed, as this is off a dev version of the
database and not up to date)

Thoughts?

--
 Magnus Hagander
 Me: https://www.hagander.net/
 Work: https://www.redpill-linpro.com/

docs_update.patch (11K) Download Attachment
2020-11-23_16-58.png (159K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Bruce Momjian
On Mon, Nov 23, 2020 at 05:01:10PM +0100, Magnus Hagander wrote:
> I'm also attaching a screenshot of the main docs page with the
> changes, for those that can't easily test a website patch. (Nevermind
> the actual versions listed, as this is off a dev version of the
> database and not up to date)

Yes, this makes a lot of sense.

--
  Bruce Momjian  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee



Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

David G Johnston
On Mon, Nov 23, 2020 at 9:08 AM Bruce Momjian <[hidden email]> wrote:
On Mon, Nov 23, 2020 at 05:01:10PM +0100, Magnus Hagander wrote:
> I'm also attaching a screenshot of the main docs page with the
> changes, for those that can't easily test a website patch. (Nevermind
> the actual versions listed, as this is off a dev version of the
> database and not up to date)

Yes, this makes a lot of sense.


+many

This is a larger complaint than this patch should resolve but I find that having links to other resources only appear in the Quick Links sidebar makes them very easy to overlook.  Adding a small blurb informing the reader of the existence of additional pages and pointing out the sidebar would improve usability IMO.  For the documentation page I'd add that blurb between the button and the manuals section.  The "What will you find here?" on the Developers page is a good example.

David J.

Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Adrian Klaver-4
In reply to this post by Magnus Hagander-2
On 11/23/20 8:01 AM, Magnus Hagander wrote:

> I think it requires a silly number of steps to get to our
> documentation today. It's not huge, but it's "click documentation,
> click "current manuals", click 13". And the actual /docs/ page is
> mostly empty, which makes it a waste.
>
> PFA a patch that changes this:
>
> * The /docs/ page now gets direct links to all supported documentation
> versions, including PDFs
>
> * The /docs/ page gets a big button that sends you directly to
> /docs/current/ -- that link wasn't  available at all before
>
> * Translated manuals were listed both on the left and right sidebar on
> the root docs page, but not on the manuals page. Remove them from the
> left sidebar, leave them on the right one since it's now on the root
> docs page.
>
> Unrelated to the restructuring, but while at it:
> * Make the left column in the manuals table not take 50% of the width
> when all it has is a number
>
> * Add a link to the developer docs
>
> * Remove the repetitive "comprehensive manual" text (it's no more
> comprehensive than the other manual, it's just a different format),
> and insert a proper separator between the two PDF versions
>
> * Remove some redundant and incorrect template tags probably resulting
> from previous copy/paste mistakes
>
> I'm also attaching a screenshot of the main docs page with the
> changes, for those that can't easily test a website patch. (Nevermind
> the actual versions listed, as this is off a dev version of the
> database and not up to date)
>
> Thoughts?
>

+1


--
Adrian Klaver
[hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Stephen Frost
In reply to this post by Magnus Hagander-2
Greetings,

* Magnus Hagander ([hidden email]) wrote:
> I think it requires a silly number of steps to get to our
> documentation today. It's not huge, but it's "click documentation,
> click "current manuals", click 13". And the actual /docs/ page is
> mostly empty, which makes it a waste.

+many

Thanks,

Stephen

signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Jonathan S. Katz-3
In reply to this post by Magnus Hagander-2
On 11/23/20 11:01 AM, Magnus Hagander wrote:

> I think it requires a silly number of steps to get to our
> documentation today. It's not huge, but it's "click documentation,
> click "current manuals", click 13". And the actual /docs/ page is
> mostly empty, which makes it a waste.
>
> PFA a patch that changes this:
>
> * The /docs/ page now gets direct links to all supported documentation
> versions, including PDFs
>
> * The /docs/ page gets a big button that sends you directly to
> /docs/current/ -- that link wasn't  available at all before
I would bikeshed the text on this slightly, perhaps: "Current
Documentation" or "Latest Documentation".

I'd be ok with "View Current Documentation" as well.

>
> * Translated manuals were listed both on the left and right sidebar on
> the root docs page, but not on the manuals page. Remove them from the
> left sidebar, leave them on the right one since it's now on the root
> docs page.
>
> Unrelated to the restructuring, but while at it:
> * Make the left column in the manuals table not take 50% of the width
> when all it has is a number
>
> * Add a link to the developer docs
>
> * Remove the repetitive "comprehensive manual" text (it's no more
> comprehensive than the other manual, it's just a different format),
> and insert a proper separator between the two PDF versions
>
> * Remove some redundant and incorrect template tags probably resulting
> from previous copy/paste mistakes
>
> I'm also attaching a screenshot of the main docs page with the
> changes, for those that can't easily test a website patch. (Nevermind
> the actual versions listed, as this is off a dev version of the
> database and not up to date)
I could not verify the PDF changes as I don't have them built locally at
the moment, but everything else looks fine.

+1,

Jonathan


OpenPGP_signature (855 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Álvaro Herrera
In reply to this post by Magnus Hagander-2
On 2020-Nov-23, Magnus Hagander wrote:

> I'm also attaching a screenshot of the main docs page with the
> changes, for those that can't easily test a website patch. (Nevermind
> the actual versions listed, as this is off a dev version of the
> database and not up to date)

.. I find it a bit annoying that if I want the current docs, I have to
avoid looking at the table, or I'll get confused until I see the button
sitting above.  IMO it would be better to include "13" in the table as
well as the button to avoid this effect (I realize this is redundant).

Maybe if the button had red text that said "13" it would not be
necessary.

Alternatively: remove the button, include "13" in the table, and have it
contain a blue tag-looking label that says "current" or something like
that.  (While at it, and to make the current dev cycle less of an
exception: change the "Development version" row to have text "14dev" in
red plus a blue label that says "In development".)


Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Jonathan S. Katz-3
On 11/23/20 4:24 PM, Alvaro Herrera wrote:

> On 2020-Nov-23, Magnus Hagander wrote:
>
>> I'm also attaching a screenshot of the main docs page with the
>> changes, for those that can't easily test a website patch. (Nevermind
>> the actual versions listed, as this is off a dev version of the
>> database and not up to date)
>
> .. I find it a bit annoying that if I want the current docs, I have to
> avoid looking at the table, or I'll get confused until I see the button
> sitting above.  IMO it would be better to include "13" in the table as
> well as the button to avoid this effect (I realize this is redundant).
I think that has to do with the data on Magnus' machine -- it should
load 13 in the table.

Jonathan


OpenPGP_signature (855 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Álvaro Herrera
On 2020-Nov-23, Jonathan S. Katz wrote:

> On 11/23/20 4:24 PM, Alvaro Herrera wrote:
> > On 2020-Nov-23, Magnus Hagander wrote:
> >
> >> I'm also attaching a screenshot of the main docs page with the
> >> changes, for those that can't easily test a website patch. (Nevermind
> >> the actual versions listed, as this is off a dev version of the
> >> database and not up to date)
> >
> > .. I find it a bit annoying that if I want the current docs, I have to
> > avoid looking at the table, or I'll get confused until I see the button
> > sitting above.  IMO it would be better to include "13" in the table as
> > well as the button to avoid this effect (I realize this is redundant).
>
> I think that has to do with the data on Magnus' machine -- it should
> load 13 in the table.

Oh!  Never mind that, then.



Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

David G Johnston
In reply to this post by Álvaro Herrera
On Mon, Nov 23, 2020 at 2:24 PM Alvaro Herrera <[hidden email]> wrote:
On 2020-Nov-23, Magnus Hagander wrote:

> I'm also attaching a screenshot of the main docs page with the
> changes, for those that can't easily test a website patch. (Nevermind
> the actual versions listed, as this is off a dev version of the
> database and not up to date)

.. I find it a bit annoying that if I want the current docs, I have to
avoid looking at the table, or I'll get confused until I see the button
sitting above.  IMO it would be better to include "13" in the table as
well as the button to avoid this effect (I realize this is redundant).

Maybe if the button had red text that said "13" it would not be
necessary.

Alternatively: remove the button, include "13" in the table, and have it
contain a blue tag-looking label that says "current" or something like
that.  (While at it, and to make the current dev cycle less of an
exception: change the "Development version" row to have text "14dev" in
red plus a blue label that says "In development".)


FWIW I noticed this to, the re-read the email and noticed:

"(Nevermind the actual versions listed, as this is off a dev version of the
database and not up to date)"
 
And figured the two were related.

An idea while I'm here - It is still a couple of clicks and screen searching to get to the current docs.  How about an icon on the main page, next to the search icon (more useful for frequent users), that takes you immediately to the current documentation webpage?  And/Or a third button in the banner (download, new?) for "Current Manual" (more useful for newer readers)?

David J.


Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Magnus Hagander-2
On Mon, Nov 23, 2020 at 10:33 PM David G. Johnston
<[hidden email]> wrote:

>
> On Mon, Nov 23, 2020 at 2:24 PM Alvaro Herrera <[hidden email]> wrote:
>>
>> On 2020-Nov-23, Magnus Hagander wrote:
>>
>> > I'm also attaching a screenshot of the main docs page with the
>> > changes, for those that can't easily test a website patch. (Nevermind
>> > the actual versions listed, as this is off a dev version of the
>> > database and not up to date)
>>
>> .. I find it a bit annoying that if I want the current docs, I have to
>> avoid looking at the table, or I'll get confused until I see the button
>> sitting above.  IMO it would be better to include "13" in the table as
>> well as the button to avoid this effect (I realize this is redundant).
>>
>> Maybe if the button had red text that said "13" it would not be
>> necessary.
>>
>> Alternatively: remove the button, include "13" in the table, and have it
>> contain a blue tag-looking label that says "current" or something like
>> that.  (While at it, and to make the current dev cycle less of an
>> exception: change the "Development version" row to have text "14dev" in
>> red plus a blue label that says "In development".)
>>
>
> FWIW I noticed this to, the re-read the email and noticed:
>
> "(Nevermind the actual versions listed, as this is off a dev version of the
> database and not up to date)"
>
> And figured the two were related.

That is indeed exactly what I was referring to :)


> An idea while I'm here - It is still a couple of clicks and screen searching to get to the current docs.  How about an icon on the main page, next to the search icon (more useful for frequent users), that takes you immediately to the current documentation webpage?  And/Or a third button in the banner (download, new?) for "Current Manual" (more useful for newer readers)?

Yeah, it makes sense to do something like that, I agree. I'll take a
look at that as a separate patch later, and post a separate proposal.

//Magnus


Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Magnus Hagander-2
In reply to this post by Jonathan S. Katz-3
On Mon, Nov 23, 2020 at 6:23 PM Jonathan S. Katz <[hidden email]> wrote:

>
> On 11/23/20 11:01 AM, Magnus Hagander wrote:
> > I think it requires a silly number of steps to get to our
> > documentation today. It's not huge, but it's "click documentation,
> > click "current manuals", click 13". And the actual /docs/ page is
> > mostly empty, which makes it a waste.
> >
> > PFA a patch that changes this:
> >
> > * The /docs/ page now gets direct links to all supported documentation
> > versions, including PDFs
> >
> > * The /docs/ page gets a big button that sends you directly to
> > /docs/current/ -- that link wasn't  available at all before
>
> I would bikeshed the text on this slightly, perhaps: "Current
> Documentation" or "Latest Documentation".
>
> I'd be ok with "View Current Documentation" as well.

I had that first, but then realized that we have least previously
separated out "documentation" (all of it) from "Manuals" (explicitly
the stuff built from the SGML sources). I didn't want to change that
terminology as part of a restructure, as it would probably have
effects on other places too.



--
 Magnus Hagander
 Me: https://www.hagander.net/
 Work: https://www.redpill-linpro.com/


Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Jonathan S. Katz-3
On 11/23/20 5:49 PM, Magnus Hagander wrote:

> On Mon, Nov 23, 2020 at 6:23 PM Jonathan S. Katz <[hidden email]> wrote:
>>
>> On 11/23/20 11:01 AM, Magnus Hagander wrote:
>>> I think it requires a silly number of steps to get to our
>>> documentation today. It's not huge, but it's "click documentation,
>>> click "current manuals", click 13". And the actual /docs/ page is
>>> mostly empty, which makes it a waste.
>>>
>>> PFA a patch that changes this:
>>>
>>> * The /docs/ page now gets direct links to all supported documentation
>>> versions, including PDFs
>>>
>>> * The /docs/ page gets a big button that sends you directly to
>>> /docs/current/ -- that link wasn't  available at all before
>>
>> I would bikeshed the text on this slightly, perhaps: "Current
>> Documentation" or "Latest Documentation".
>>
>> I'd be ok with "View Current Documentation" as well.
>
> I had that first, but then realized that we have least previously
> separated out "documentation" (all of it) from "Manuals" (explicitly
> the stuff built from the SGML sources). I didn't want to change that
> terminology as part of a restructure, as it would probably have
> effects on other places too.
"Current Manual", "Latest Manual", or "View Current Manual" then :)

Jonathan


OpenPGP_signature (855 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Magnus Hagander-2
On Tue, Nov 24, 2020 at 12:03 AM Jonathan S. Katz <[hidden email]> wrote:

>
> On 11/23/20 5:49 PM, Magnus Hagander wrote:
> > On Mon, Nov 23, 2020 at 6:23 PM Jonathan S. Katz <[hidden email]> wrote:
> >>
> >> On 11/23/20 11:01 AM, Magnus Hagander wrote:
> >>> I think it requires a silly number of steps to get to our
> >>> documentation today. It's not huge, but it's "click documentation,
> >>> click "current manuals", click 13". And the actual /docs/ page is
> >>> mostly empty, which makes it a waste.
> >>>
> >>> PFA a patch that changes this:
> >>>
> >>> * The /docs/ page now gets direct links to all supported documentation
> >>> versions, including PDFs
> >>>
> >>> * The /docs/ page gets a big button that sends you directly to
> >>> /docs/current/ -- that link wasn't  available at all before
> >>
> >> I would bikeshed the text on this slightly, perhaps: "Current
> >> Documentation" or "Latest Documentation".
> >>
> >> I'd be ok with "View Current Documentation" as well.
> >
> > I had that first, but then realized that we have least previously
> > separated out "documentation" (all of it) from "Manuals" (explicitly
> > the stuff built from the SGML sources). I didn't want to change that
> > terminology as part of a restructure, as it would probably have
> > effects on other places too.
>
> "Current Manual", "Latest Manual", or "View Current Manual" then :)

Oh, I thought your issue with it was specifically the use of the word
Manual and not Documentation :)

While that may be further nitpicking, but those aren't correct are
they? That is, *all* the manuals we put up are the current (or latest)
ones, they're just for different versions. Even in our archive we only
keep the very latest ones for each version, not actually older
manuals. So "current" is only really correct if it also includes
"version"..

I assume what you were after, without saying so, was to make it shorter?

We could make it just "current version", but I'm not sure that's
really an improvement?

Or just "view the manual" and assume that anybody who actually cares
about a specific version will go directly to the table, maybe with an
ingress text of "To view the manual for an older version, pick your
version in the table below" above the table?

--
 Magnus Hagander
 Me: https://www.hagander.net/
 Work: https://www.redpill-linpro.com/


Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Daniel Gustafsson
> On 24 Nov 2020, at 10:45, Magnus Hagander <[hidden email]> wrote:

> Or just "view the manual" and assume that anybody who actually cares
> about a specific version will go directly to the table, maybe with an
> ingress text of "To view the manual for an older version, pick your
> version in the table below" above the table?

+1

cheers ./daniel


Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Jonathan S. Katz-3
On 11/24/20 4:55 AM, Daniel Gustafsson wrote:
>> On 24 Nov 2020, at 10:45, Magnus Hagander <[hidden email]> wrote:
>
>> Or just "view the manual" and assume that anybody who actually cares
>> about a specific version will go directly to the table, maybe with an
>> ingress text of "To view the manual for an older version, pick your
>> version in the table below" above the table?
>
> +1

Sure, that works.

Jonathan


OpenPGP_signature (855 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Magnus Hagander-2
On Tue, Nov 24, 2020 at 5:15 PM Jonathan S. Katz <[hidden email]> wrote:

>
> On 11/24/20 4:55 AM, Daniel Gustafsson wrote:
> >> On 24 Nov 2020, at 10:45, Magnus Hagander <[hidden email]> wrote:
> >
> >> Or just "view the manual" and assume that anybody who actually cares
> >> about a specific version will go directly to the table, maybe with an
> >> ingress text of "To view the manual for an older version, pick your
> >> version in the table below" above the table?
> >
> > +1
>
> Sure, that works.
Thanks, I've pushed this version.

For the suggested changes to the frontpage, I suggest the attached.

Or should it link directly to the /docs/current/ url?

--
 Magnus Hagander
 Me: https://www.hagander.net/
 Work: https://www.redpill-linpro.com/

docs_frontpage_button.patch (862 bytes) Download Attachment
2020-11-24_17-25.png (621K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Jonathan S. Katz-3
On 11/24/20 11:27 AM, Magnus Hagander wrote:

> On Tue, Nov 24, 2020 at 5:15 PM Jonathan S. Katz <[hidden email]> wrote:
>>
>> On 11/24/20 4:55 AM, Daniel Gustafsson wrote:
>>>> On 24 Nov 2020, at 10:45, Magnus Hagander <[hidden email]> wrote:
>>>
>>>> Or just "view the manual" and assume that anybody who actually cares
>>>> about a specific version will go directly to the table, maybe with an
>>>> ingress text of "To view the manual for an older version, pick your
>>>> version in the table below" above the table?
>>>
>>> +1
>>
>> Sure, that works.
>
> Thanks, I've pushed this version.
>
> For the suggested changes to the frontpage, I suggest the attached.
>
> Or should it link directly to the /docs/current/ url?
+1 for just /docs/ -- good for all users.

If we're adding the documentation button there to the homepage, I would
drop the "New to PostgreSQL" button from it. We have a section on "New
to PostgreSQL" just below there, and it is still above the proverbial
fold (at least on a non-mobile device).

Jonathan


OpenPGP_signature (855 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

Magnus Hagander-2
On Tue, Nov 24, 2020 at 5:29 PM Jonathan S. Katz <[hidden email]> wrote:

>
> On 11/24/20 11:27 AM, Magnus Hagander wrote:
> > On Tue, Nov 24, 2020 at 5:15 PM Jonathan S. Katz <[hidden email]> wrote:
> >>
> >> On 11/24/20 4:55 AM, Daniel Gustafsson wrote:
> >>>> On 24 Nov 2020, at 10:45, Magnus Hagander <[hidden email]> wrote:
> >>>
> >>>> Or just "view the manual" and assume that anybody who actually cares
> >>>> about a specific version will go directly to the table, maybe with an
> >>>> ingress text of "To view the manual for an older version, pick your
> >>>> version in the table below" above the table?
> >>>
> >>> +1
> >>
> >> Sure, that works.
> >
> > Thanks, I've pushed this version.
> >
> > For the suggested changes to the frontpage, I suggest the attached.
> >
> > Or should it link directly to the /docs/current/ url?
>
> +1 for just /docs/ -- good for all users.
>
> If we're adding the documentation button there to the homepage, I would
> drop the "New to PostgreSQL" button from it. We have a section on "New
> to PostgreSQL" just below there, and it is still above the proverbial
> fold (at least on a non-mobile device).

That's a good point -- in particular the "just below" part. So yeah,
let's drop that one.

--
 Magnus Hagander
 Me: https://www.hagander.net/
 Work: https://www.redpill-linpro.com/


Reply | Threaded
Open this post in threaded view
|

Re: Update to docs root pages and navigation

David G Johnston
In reply to this post by Jonathan S. Katz-3
On Tue, Nov 24, 2020 at 9:29 AM Jonathan S. Katz <[hidden email]> wrote:
On 11/24/20 11:27 AM, Magnus Hagander wrote:
> On Tue, Nov 24, 2020 at 5:15 PM Jonathan S. Katz <[hidden email]> wrote:
>>
>> On 11/24/20 4:55 AM, Daniel Gustafsson wrote:
>>>> On 24 Nov 2020, at 10:45, Magnus Hagander <[hidden email]> wrote:
>>>
>>>> Or just "view the manual" and assume that anybody who actually cares
>>>> about a specific version will go directly to the table, maybe with an
>>>> ingress text of "To view the manual for an older version, pick your
>>>> version in the table below" above the table?
>>>
>>> +1
>>
>> Sure, that works.
>
> Thanks, I've pushed this version.
>
> For the suggested changes to the frontpage, I suggest the attached.
>
> Or should it link directly to the /docs/current/ url?

+1 for just /docs/ -- good for all users.


If it doesn't go directly to /current I don't think including it is worthwhile - the main navigation gets you to the full page.

All users benefit from reading the current version documentation even if they are running older versions.

David J.

12