From: Ricardo Wurmus <rekado@elephly.net>
To: Laura Lazzati <laura.lazzati.15@gmail.com>
Cc: guix-devel@gnu.org
Subject: Re: We need your feedback of the documentation videos!
Date: Wed, 17 Jul 2019 11:44:09 +0200 [thread overview]
Message-ID: <87d0i9gfme.fsf@elephly.net> (raw)
In-Reply-To: <CAPNLzUOv3pxy4eRVban3UuCr1P9wgY3vp-d+C_eDQP_O+OW0wQ@mail.gmail.com>
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
next prev parent reply other threads:[~2019-07-17 9:44 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-07-16 15:11 We need your feedback of the documentation videos! Laura Lazzati
2019-07-16 17:40 ` pelzflorian (Florian Pelz)
2019-07-17 6:31 ` Dimakakos Dimos
2019-07-17 7:55 ` pelzflorian (Florian Pelz)
2019-07-30 14:37 ` pelzflorian (Florian Pelz)
2019-07-17 7:11 ` Tanguy Le Carrour
2019-07-17 9:44 ` Ricardo Wurmus [this message]
2019-07-30 13:26 ` Laura Lazzati
2019-07-30 15:03 ` Tobias Geerinckx-Rice
2019-07-30 17:12 ` Tobias Geerinckx-Rice
2019-07-30 14:06 ` pelzflorian (Florian Pelz)
2019-08-08 15:04 ` Laura Lazzati
2019-08-08 15:48 ` Ricardo Wurmus
2019-08-13 18:03 ` Laura Lazzati
2019-08-25 18:55 ` Laura Lazzati
2019-10-17 4:34 ` pelzflorian (Florian Pelz)
2019-10-19 20:13 ` Ludovic Courtès
2019-10-19 21:00 ` pelzflorian (Florian Pelz)
2019-10-22 12:05 ` pelzflorian (Florian Pelz)
2019-10-22 16:25 ` sirgazil
2019-10-22 18:59 ` pelzflorian (Florian Pelz)
2019-10-23 11:49 ` pelzflorian (Florian Pelz)
2019-10-23 14:33 ` sirgazil
2019-10-25 6:35 ` pelzflorian (Florian Pelz)
2019-10-25 8:12 ` pelzflorian (Florian Pelz)
2019-10-25 14:25 ` sirgazil
2019-10-25 20:32 ` Ludovic Courtès
2019-10-25 21:58 ` pelzflorian (Florian Pelz)
2019-10-26 14:29 ` pelzflorian (Florian Pelz)
2019-10-27 19:47 ` sirgazil
2019-10-28 7:41 ` pelzflorian (Florian Pelz)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87d0i9gfme.fsf@elephly.net \
--to=rekado@elephly.net \
--cc=guix-devel@gnu.org \
--cc=laura.lazzati.15@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).