Re: We need your feedback of the documentation videos!

[Ricardo Wurmus]

Hi Laura,

> https://archive.org/details/guix-videos and give feedback here :)

I second the praise these videos have received.  I’m very happy to see
them close to completion.  I haven’t watched all of them yet, but I
noticed a couple of things while browsing them.

Here are some comments about 01-installation-from-script:

- at 01:15 the URL is broken in an odd manner.  This can be fixed in one
  of these ways:

  a) use a shorter existing URL:
  https://git.sv.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
  b) realize that the URL is still too long and create an alias at
  https://guix.gnu.org/install.sh and use that.

- at 01:20 the GPG key is fetched from the SKS servers, which expose
  users to attacks.  This should be replaced with the new method to
  fetch the GPG key.

- at 01:30 Ludo’s name is mangled.  Looks like an encoding problem.

- at 01:35 the output has been altered.  We are not using stars in the
  logo.  What is the reason for altering the output?

- at 02:00 the output looks odd… is the script really creating
  “<guixbuilder01 to 10>” and then again “<guixbuilder08>”?  If this has
  been edited: why?

- at 02:15 the way “# yes” is input would not work in real life because
  “# yes” is not “yes”.  Is this a limitation of the video generation
  scripts?

- at 02:20 it mentions ci.guix.info, but it should be ci.guix.gnu.org.

- at 02:50 the command should probably be “guix install hello” instead
  of “guix package -i hello”.

- at the same mark there is a series of dots, which is not produced by
  Guix.  Why have they been added?

- at 02:55 the environment variable hint is outdated.  Guix now prints
  something shorter.

- at 3:10 the URL is printed in italics, which makes it harder to read.
  We should probably use “https://guix.gnu.org/manual”.

Here are some comments about 02-everyday-use-part-one:

- the command “guix package --install hello” is used, but “guix install
  hello” might be better

- the output refers to “ci.guix.info”, but it should be
  “ci.guix.gnu.org”.

- the output is wrapped in an unfortunate place (right before the 100%)

- we should replace the long store hashes with “…” so that fewer lines
  need to be wrapped around.

- the environment variable hint is outdated.  Guix displays something
  more concise now.

- there are a bunch of dots before “2 packages in profile”, which are
  not produced by Guix.

- it’s confusing that it mentions “2 packages” because we didn’t see
  anyone install the glibc-locales package.

- at 2:58 there are two different fonts in use, but I can’t tell why.
  The diagram also seems a little confusing to me.  If it’s supposed to
  be read as a flow chart it would be better to use flow chart
  conventions.

- at 4:03 the URL is printed in italics, which makes it harder to read.
  We should probably use “https://guix.gnu.org/manual”.

Some comments about 02-everyday-use-part-two:

- at 00:21 you show a URL to the previous video.  I’d suggest removing
  that as the URL is long and might change.

- at 00:26 “guix pull” appears twice, which is confusing.  I don’t know
  what the arrows mean.

- at 01:01 I don’t understand why there is an arrow from “Garbage
  collector” to “guix gc”.  They are the same.

- at 02:21 there is again a series of dots, which are not produced by
  Guix.  As mentioned before I suggest trimming the store hashes.

- at 02:26 the URL should be https://guix.gnu.org/manual and not be
  printed in italics.

Comments about the video 03-help:

- at 00:20 the fonts and styles are mixed.  Please don’t use all caps.
  I also think it’s a bit …  odd to self-advertise as “kind” and “warm”.
  (This may be true, but it’s for others to assess.)  I would spell out
  “CoC” because that may not mean much to people.

- at 00:45 the URL is using a different font than the URL at the end of
  each video.  It probably should be https://guix.gnu.org.

- at 01:00 the URL for the manual is wrong.  It should be
  https://guix.gnu.org/manual.

- at 01:10 same comment about the font, italics, and the URL :)

- 1:30 looks really crammed.  I think it would be better to remove the
  header “Our website” from all but the first mention of the website.
  There does not need to be a “section indicator” on every slide — the
  videos are short enough to not need them.

- at 2:20 “subscribing to a mailman” sounds unintentionally funny.  I’d
  probably turn that into “Mailing lists” or skip the header completely.

- at 3:05 same comment about the slide being a bit stuffed.  There’s too
  much on the slide.  We could split that up into several slides or
  remove parts of it.

- at 4:10 the URL should not be in italics and it should be
  https://guix.gnu.org

What does everyone think about these points?

--
Ricardo