The Web manual situation is still needlessly confusing

OpenSubmitted by Tobias Geerinckx-Rice.
Details
4 participants
  • Efraim Flashner
  • John Kehayias
  • Tobias Geerinckx-Rice
  • zimoun
Owner
unassigned
Severity
normal
T
T
Tobias Geerinckx-Rice wrote on 4 Oct 00:12 +0200
(name . Bug reports for GNU Guix)(address . bug-guix@gnu.org)
87ilydycps.fsf@nckx
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
-----BEGIN PGP SIGNATURE-----
iIMEARYKACsWIQT12iAyS4c9C3o4dnINsP+IT1VteQUCYVosIA0cbWVAdG9iaWFzLmdyAAoJEA2w/4hPVW15uOkA/jrtFZbSAv+twHdy3r7sIFZ3POJPJm+kQOahb2zkVOgCAP4pumzKl5gVxn3VvAnFxhx9L37AC8LByXyHLqtCmv3/CA===yHWb-----END PGP SIGNATURE-----
J
J
John Kehayias wrote on 4 Oct 06:19 +0200
(name . 51000@debbugs.gnu.org)(address . 51000@debbugs.gnu.org)
susz0kTIZduiBm3i-bxbWioXd1-7m0GKVQJHBNMOHlb7o-yzcFfKyFS77l1TZEZuag_GtYjhtIJmZflLEbZNZbTMIYwNbX6Rgluz0O6KEuA=@protonmail.com
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
E
E
Efraim Flashner wrote on 4 Oct 08:31 +0200
Re: bug#51000: The Web manual situation is still needlessly confusing
(name . Tobias Geerinckx-Rice)(address . me@tobias.gr)(address . 51000@debbugs.gnu.org)
YVqf32IHhqhf/RDr@3900XT
On Mon, Oct 04, 2021 at 12:12:55AM +0200, Tobias Geerinckx-Rice via Bug reports for GNU Guix wrote:
Toggle quote (19 lines)> 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 manuallocations. It doesn't take into account any changes needed in thewebsite 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 8351Confidentiality cannot be guaranteed on emails sent or received unencrypted
From 5ae07d5d8db78d3f190a8780ba2eeaa5ce2c1be1 Mon Sep 17 00:00:00 2001Message-Id: <5ae07d5d8db78d3f190a8780ba2eeaa5ce2c1be1.1633329044.git.efraim@flashner.co.il>From: Efraim Flashner <efraim@flashner.co.il>Date: Mon, 4 Oct 2021 09:28:20 +0300Subject: [PATCH] hydra: Move guix-manual URLs.
This is likely to remove some ambiguity for which manual to use.
* hydra/berlin.scm (operating-system)[services]: Adjuststatic-website-service-type services to change the locations of thegenerated guix manuals.* hydra/nginx/berlin.scm (guix.gnu.org-other-locations): Adjustnginx-location-configuration for the manual locations.--- hydra/berlin.scm | 7 ++++--- hydra/nginx/berlin.scm | 10 +++++----- 2 files changed, 9 insertions(+), 8 deletions(-)
Toggle diff (60 lines)diff --git a/hydra/berlin.scm b/hydra/berlin.scmindex 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-variablesdiff --git a/hydra/nginx/berlin.scm b/hydra/nginx/berlin.scmindex 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
-----BEGIN PGP SIGNATURE-----
iQIzBAABCgAdFiEEoov0DD5VE3JmLRT3Qarn3Mo9g1EFAmFan98ACgkQQarn3Mo9g1FWHQ/7BSr3r7g4nYE0ihSWgPLZAWHZDN1jWUvMkQjzmMR0UMrm2++9oRtv/6satd19oK8hHxXoGVkVlshsGBmP6Oe0KLnvwOkNprMRh/lBspqt00F3t7g2cBjiitGXsV42yiBCpzUyBi5jaBSJcH6uRpPC9x+c74jPqouvsnrcm0TIL0zStAF15Re/y5gkM5vN5pryorSvfzW7WwOFV+xOoiRlZsqNI3AUuxrvCAf8ecTUqJYJbblMj9ZnRhz2yqFEFSg63UPbpbRyoADxyF+yRrcc81S5CtURBRtgLtoKpB0OsAnstWrnTDsekmqC4Ce2nBPyS5SfAr0YlLA9EL7gpibqs83BKH8g5Kif8in3TmmQqAx6pZjAbMjK0wCgUU/T8MLsf0D9zL2ll0YZlCbGhaX6/gsHZL4SztyJytRSSKNUbj60O1FSevK2a3iI+ZZ1aE7YRgIgHCOCAV+9rPkdJUn9jaQQzVQN3bgSy18/xWWZiG5KUZRYVIy3umaRRrkl8nFPa2paStQIck8UhNvSX+RO58kYEruytS3JULsAZesqOmqYicOgOSOJ3oDP2prWGGPBrjb9LK5haU+H4G+svK4tMBHqoP4DNS3gjoC2C75iGvZxFQyDz8SNEbrvXVUitay3kfC9AclPyLnXbmitt8Q5ilRaE4Jte75xU+2qUuw2Yxo==o7iz-----END PGP SIGNATURE-----

Z
Z
zimoun wrote on 4 Oct 08:58 +0200
864k9xff98.fsf@gmail.com
Hi,
On Mon, 04 Oct 2021 at 00:12, Tobias Geerinckx-Rice via Bug reports for GNU Guix <bug-guix@gnu.org> wrote:
Toggle quote (7 lines)> - 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
?
Your comment

Commenting via the web interface is currently disabled.

To comment on this conversation send email to 51000@debbugs.gnu.org