bug#51000: The Web manual situation is still needlessly confusing

bug#51000: The Web manual situation is still needlessly confusing

[Tobias Geerinckx-Rice via Bug reports for GNU Guix]

[-- Attachment #1: Type: text/plain, Size: 735 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 247 bytes --]

bug#51000: The Web manual situation is still needlessly confusing

[John Kehayias via Bug reports for GNU Guix]

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

bug#51000: The Web manual situation is still needlessly confusing

[Efraim Flashner]

[-- Attachment #1.1: Type: text/plain, Size: 1245 bytes --]

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@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

[-- Attachment #1.2: 0001-hydra-Move-guix-manual-URLs.patch --]
[-- Type: text/plain, Size: 3468 bytes --]

From 5ae07d5d8db78d3f190a8780ba2eeaa5ce2c1be1 Mon Sep 17 00:00:00 2001
Message-Id: <5ae07d5d8db78d3f190a8780ba2eeaa5ce2c1be1.1633329044.git.efraim@flashner.co.il>
From: Efraim Flashner <efraim@flashner.co.il>
Date: Mon, 4 Oct 2021 09:28:20 +0300
Subject: [PATCH] hydra: Move guix-manual URLs.

This is likely to remove some ambiguity for which manual to use.

* hydra/berlin.scm (operating-system)[services]: Adjust
static-website-service-type services to change the locations of the
generated guix manuals.
* hydra/nginx/berlin.scm (guix.gnu.org-other-locations): Adjust
nginx-location-configuration for the manual locations.
---
 hydra/berlin.scm       |  7 ++++---
 hydra/nginx/berlin.scm | 10 +++++-----
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/hydra/berlin.scm b/hydra/berlin.scm
index 146173b..44324cf 100644
--- a/hydra/berlin.scm
+++ b/hydra/berlin.scm
@@ -300,7 +300,8 @@ Happy hacking!\n"))
                       (static-web-site-configuration
                        (git-url "https://git.savannah.gnu.org/git/guix.git")
                        (git-ref '(branch . "version-1.3.0"))
-                       (directory "/srv/guix-manual")
+                       (directory "/srv/guix-manual-1.3.0")
+                       (cache-directory "guix-manual-1.3.0")
                        (build-file "doc/build.scm")
                        (environment-variables
                          '(("GUIX_MANUAL_VERSION" . "1.3.0")
@@ -310,7 +311,7 @@ Happy hacking!\n"))
              (service static-web-site-service-type
                       (static-web-site-configuration
                        (git-url "https://git.savannah.gnu.org/git/guix.git")
-                       (directory "/srv/guix-manual-devel")
+                       (directory "/srv/guix-manual")
 
                        ;; XXX: Use a different cache directory to work around
                        ;; the fact that (guix git) would use a same-named
@@ -318,7 +319,7 @@ Happy hacking!\n"))
                        ;; above.  Since both mcron jobs run at the same time,
                        ;; they would end up using one branch or the other, in
                        ;; a non-deterministic way.
-                       (cache-directory "guix-master-manual")
+                       (cache-directory "guix-manual")
 
                        (build-file "doc/build.scm")
                        (environment-variables
diff --git a/hydra/nginx/berlin.scm b/hydra/nginx/berlin.scm
index 44ff28e..14a94fe 100644
--- a/hydra/nginx/berlin.scm
+++ b/hydra/nginx/berlin.scm
@@ -768,14 +768,14 @@ PUBLISH-URL."
                 "alias /srv/guix.gnu.org/static;")))
 
    ;; These rules take precedence over the '.pdf' and '.html' rules below.
-   (nginx-location-configuration
-    (uri "~ /manual/devel/(.*)$")
-    (body (list "expires 4h;"
-                "alias /srv/guix-manual-devel/$1;")))
    (nginx-location-configuration
     (uri "~ /manual/(.*)$")
-    (body (list "expires 1d;"
+    (body (list "expires 4h;"
                 "alias /srv/guix-manual/$1;")))
+   (nginx-location-configuration
+    (uri "~ /manual/1.3.0/(.*)$")
+    (body (list "expires 1d;"
+                "alias /srv/guix-manual-1.3.0/$1;")))
    (nginx-location-configuration
     (uri "~ /cookbook/(.*)$")
     (body (list "expires 4h;"

base-commit: 3069d5e8c8b00162af1d6e7705c8d235f2e3b56a
-- 
2.33.0


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

bug#51000: The Web manual situation is still needlessly confusing

[zimoun]

Hi,

On Mon, 04 Oct 2021 at 00:12, Tobias Geerinckx-Rice via Bug reports for GNU Guix <bug-guix@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

bug#51000: Please drop web manuals for released versions

[Felix Lechner via Bug reports for GNU Guix]

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@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

bug#51000: The Web manual situation is still needlessly confusing

[Simon Tournier]

Hi,

On Mon, 04 Oct 2021 at 00:12, Tobias Geerinckx-Rice <me@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@gnu.org>
        Mon, 25 Sep 2023 04:05:43 -0400
        id:rt-4.2.16-14-g9a593ee-17542-1695629143-1144.1975364-8-0@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@rt.gnu.org
        https://yhetil.org/guix/rt-4.2.16-14-g9a593ee-17542-1695629143-1144.1975364-8-0@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