Subject: Re: bug#62160: Guix reference manual link from guix.gnu.org?

From: Simon Tournier <[email-masked]>
Date: Tue, 14 Mar 2023 12:29:11 +0100

Hi Simon,

On Mon, 13 Mar 2023 at 13:11, Simon Josefsson via Bug reports for GNU Guix <[email-masked]> wrote:

> I often go to guix.gnu.org to read the (excellent!) Guix manual.  This
> leads to this click pattern: guix.gnu.org -> Help -> GNU Guix Manual
> 1.4.0 which leads me to a page (written in english) to chose language
> of the manual -- https://guix.gnu.org/en/manual/ -- and when I chose
> English I get a page to chose format of manual --
> https://guix.gnu.org/en/manual/en/ -- and that choice takes a split
> second cognitive load.

Well, personally I never read en/manual/ but always en/manual/devel/. :-)

And I have a short-cut (or bookmark) for opening
<https://guix.gnu.org/en/manual/devel/en/guix.html>.

> How about these changes to improve user experience?
>
> 1) The link guix.gnu.org -> Help -> GNU Guix Manual 1.4.0 goes directly
> to the split-node https://guix.gnu.org/en/manual/en/html_node/

Well, I do not have an opinion since I barely read released manual but
only the more accurate devel manual.

However, my preference is about ’entirely on one page’ an not ’with a
separate page per node’ because ’entirely on one page’ eases Control-f
for searching. :-)

>   1b) The link could respect the language-choice for the web-site,
> i.e., so if I'm browsing https://guix.gnu.org/de/ it should directly
> link me to https://guix.gnu.org/de/manual/de/html_node/ instead.

With this change, where can I choose the language for the manual?

The workflow would be,

    From https://guix.gnu.org/
    Click top right to language and select one, say French
    Then click Aide -> Manuel and it would open the manual in French.

so I would have to come back the front page to switch from one language
to the other.  Right?

Well, in addition, I would like to have a page proposition the manual
for all the languages, as we have now.  For example, these two webpages:

https://guix.gnu.org/en/manual/devel/
https://guix.gnu.org/fr/manual/devel/

serve the same choice and I would like to keep it somewhere.

> 2) Add links to the PDF variant and full-HTML variants in the top-right
> menu where different languages are shown.

Do you mean add an item to the list,

--8<---------------cut here---------------start------------->8---
      ,(menu-dropdown
        #:label (C_ "website menu" "Help")
[...]
             (menu-item #:label "All"
[...]
         (menu-item #:label (C_ "website menu"
                                (string-append "GNU Guix Manual "
[...]
             (menu-item #:label "GNU Guix Manual (latest)"
[...]
             (menu-item #:label "Guix Reference Card"
[...]
             (menu-item #:label "Videos"
[...]
             (menu-item #:label "Cookbook"
[...]
             (menu-item #:label "GNU Manuals"
[...]
             (menu-item #:label "Wiki"
[...]
             (menu-item #:label "IRC Chat"
[...]
             (menu-item #:label "Mailing Lists"
--8<---------------cut here---------------end--------------->8---

<https://git.savannah.gnu.org/cgit/guix/guix-artwork.git/tree/website/apps/base/templates/components.scm#n417>

?

Cheers,
simon