GNU bug report logs - #51000
The Web manual situation is still needlessly confusing

Previous Next

To reply to this bug, email your comments to 51000 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Tobias Geerinckx-Rice <me <at> tobias.gr>
To: Bug reports for GNU Guix <bug-guix <at> gnu.org>
Subject: The Web manual situation is still needlessly confusing
Date: Mon, 04 Oct 2021 00:12:55 +0200

[Message part 1 (text/plain, inline)]

Good evening Guix!

Nary a literal week goes by that someone doesn't post confusion 
about this or that not being in ‘the manual’, where the manual 
turns out to be <https://guix.gnu.org/manual/en/guix.html> instead 
of the one actually shipped with their Guix.

The current solution is pointing them to 
<https://guix.gnu.org/manual/devel/en/guix.html> and resetting the 
timer.

Instead:

- We should make <https://guix.gnu.org/manual/en/guix.html> the 
 ‘devel’ version, and move the stable version to to a versioned 
 URL like <https://guix.gnu.org/manual/1.3.0/en/guix.html>.

- Both manuals should have a gorgeous CSS box at the very top 
 clearly explaining their nature.

Kind regards,

T G-R

[signature.asc (application/pgp-signature, inline)]

Message #8 received at 51000 <at> debbugs.gnu.org (full text, mbox):

From: John Kehayias <john.kehayias <at> protonmail.com>
To: "51000 <at> debbugs.gnu.org" <51000 <at> debbugs.gnu.org>
Subject: Re: The Web manual situation is still needlessly confusing
Date: Mon, 04 Oct 2021 04:19:41 +0000

Hi everyone,

Definitely agree with needing this to be clearer than it is currently. As a new user I was a bit confused over the different manual versions on the website (which is still how I prefer to read the manual). As a side note, when searching online with Guix questions, I think I only see the 'stable' version come up in results.

We could perhaps be clearer in what is meant by the 'stable'/1.3.0 documentation. Seems this is mostly needed in preparing for installation (with the 1.3.0 image, not if building a current install image, of course) and during installation. Afterward, users will probably run a guix pull very soon (as in Getting Started, or as recommended by the guix command itself) and thus no longer be on the 1.3.0 manual. I'm not sure how best to communicate this on the website, but to me it is related to the next point:

I think we need something describing what we mean by Guix versions and releases, perhaps in the Intro and/or Getting Started sections (and on an About type page?). I was confused by this starting out, as I'm used to rolling distros like Arch (or, a long time ago, distros like Debian). While Guix is mostly 'rolling', we also have releases with certain package changes (like core-updates) and Guix changes. Just a simple description would I think help new users and give better context for the manual versions, however we label or make them available.

I'm happy to take a stab and making either of these points clearer, especially as one newer to Guix with these questions and assumptions nearer to mind.

John

Message #11 received at 51000 <at> debbugs.gnu.org (full text, mbox):

From: Efraim Flashner <efraim <at> flashner.co.il>
To: Tobias Geerinckx-Rice <me <at> tobias.gr>
Cc: 51000 <at> debbugs.gnu.org
Subject: Re: bug#51000: The Web manual situation is still needlessly confusing
Date: Mon, 4 Oct 2021 09:31:59 +0300

[Message part 1 (text/plain, inline)]

On Mon, Oct 04, 2021 at 12:12:55AM +0200, Tobias Geerinckx-Rice via Bug reports for GNU Guix wrote:
> Good evening Guix!
> 
> Nary a literal week goes by that someone doesn't post confusion about this
> or that not being in ‘the manual’, where the manual turns out to be
> <https://guix.gnu.org/manual/en/guix.html> instead of the one actually
> shipped with their Guix.
> 
> The current solution is pointing them to
> <https://guix.gnu.org/manual/devel/en/guix.html> and resetting the timer.
> 
> Instead:
> 
> - We should make <https://guix.gnu.org/manual/en/guix.html> the  ‘devel’
> version, and move the stable version to to a versioned  URL like
> <https://guix.gnu.org/manual/1.3.0/en/guix.html>.
> 
> - Both manuals should have a gorgeous CSS box at the very top  clearly
> explaining their nature.

Here is an untested patch against guix-maintenance to change the manual
locations. It doesn't take into account any changes needed in the
website itself to add a pointer to the 1.3.0 manual.


-- 
Efraim Flashner   <efraim <at> flashner.co.il>   רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

[0001-hydra-Move-guix-manual-URLs.patch (text/plain, attachment)]

[signature.asc (application/pgp-signature, inline)]

Message #14 received at 51000 <at> debbugs.gnu.org (full text, mbox):

From: zimoun <zimon.toutoune <at> gmail.com>
To: Tobias Geerinckx-Rice <me <at> tobias.gr>, 51000 <at> debbugs.gnu.org
Subject: Re: bug#51000: The Web manual situation is still needlessly confusing
Date: Mon, 04 Oct 2021 08:58:11 +0200

Hi,

On Mon, 04 Oct 2021 at 00:12, Tobias Geerinckx-Rice via Bug reports for GNU Guix <bug-guix <at> gnu.org> wrote:

> - We should make <https://guix.gnu.org/manual/en/guix.html> the 
>   ‘devel’ version, and move the stable version to to a versioned 
>   URL like <https://guix.gnu.org/manual/1.3.0/en/guix.html>.
>
> - Both manuals should have a gorgeous CSS box at the very top 
>   clearly explaining their nature.

Good idea. :-)

Cheers,
simon

Message #17 received at 51000 <at> debbugs.gnu.org (full text, mbox):

From: Felix Lechner <felix.lechner <at> lease-up.com>
To: 51000 <at> debbugs.gnu.org
Cc: John Kehayias <john.kehayias <at> protonmail.com>,
 Tobias Geerinckx-Rice <me <at> tobias.gr>, Efraim Flashner <efraim <at> flashner.co.il>
Subject: Please drop web manuals for released versions
Date: Sun, 21 May 2023 18:59:20 -0700

Hi,

> Here is an untested patch

Guix suffers from an unhelpful anachronism that search engines
consistently rank historical versions of the Reference Manual [1]
above the latest edition. [2] It's probably because third-parties link
to historical versions more often than they do to the current version.
Please drop the historical versions.

Historical versions are irrelevant for current users and should only
be shipped on installation media. The current edition is only a 'guix
pull' away—a command we encourage widely.

As an example for the grave but unnecessary confusion, the manual
generally perceived as official lists the incorrect email address
guix-patches <at> debbugs.gnu.org as a way to contribute to Guix. [3]

Let's not put stumbling blocks before the blind, please. I beg you,
let's think of our fellow human beings. Thanks!

Kind regards,
Felix Lechner

[1] https://guix.gnu.org/manual/en/guix.html
[2] https://guix.gnu.org/en/manual/devel/en/guix.html
[3] https://guix.gnu.org/en/manual/en/guix.html#Multiple-Patches-1

Message #20 received at 51000 <at> debbugs.gnu.org (full text, mbox):

From: Simon Tournier <zimon.toutoune <at> gmail.com>
To: Tobias Geerinckx-Rice <me <at> tobias.gr>
Cc: 51000 <at> debbugs.gnu.org
Subject: Re: bug#51000: The Web manual situation is still needlessly confusing
Date: Wed, 27 Sep 2023 11:26:54 +0200

Hi,

On Mon, 04 Oct 2021 at 00:12, Tobias Geerinckx-Rice <me <at> tobias.gr> wrote:

> Instead:
>
> - We should make <https://guix.gnu.org/manual/en/guix.html> the   ‘devel’
>   version, and move the stable version to to a versioned   URL like
>  <https://guix.gnu.org/manual/1.3.0/en/guix.html>.

Considering this hypothetical change, please note issue as reported by:

        bug#66189: [gnu.org #1975364] Broken link in Guix manual.
        "Therese Godefroy via RT" <webmasters-comment <at> gnu.org>
        Mon, 25 Sep 2023 04:05:43 -0400
        id:rt-4.2.16-14-g9a593ee-17542-1695629143-1144.1975364-8-0 <at> rt.gnu.org
        https://issues.guix.gnu.org//66189
        https://issues.guix.gnu.org/msgid/rt-4.2.16-14-g9a593ee-17542-1695629143-1144.1975364-8-0 <at> rt.gnu.org
        https://yhetil.org/guix/rt-4.2.16-14-g9a593ee-17542-1695629143-1144.1975364-8-0 <at> rt.gnu.org

Quoting:

        > https://ftp.gnu.org/gnu/guix/guix-system-vm-image-e5f7c14.x86_64-linux.qcow2
        > in
        > https://guix.gnu.org/manual/devel/en/html_node/Running-Guix-in-a-VM.html
        > is broken.

    Yes, the link is automatically generated by,

        @url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2}

    For instance, today the last manual correspond to Guix revision faf3ca
    and the link in this development manual reads,

        https://ftp.gnu.org/gnu/guix/guix-system-vm-image-fafd3ca.x86_64-linux.qcow2

    To my knowledge, no one is pushing to FTP all these images.

Cheers,
simon

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.