[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: We need your feedback of the documentation videos!
From: |
Ricardo Wurmus |
Subject: |
Re: We need your feedback of the documentation videos! |
Date: |
Wed, 17 Jul 2019 11:44:09 +0200 |
User-agent: |
mu4e 1.2.0; emacs 26.2 |
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