From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ricardo Wurmus Subject: Re: We need your feedback of the documentation videos! Date: Wed, 17 Jul 2019 11:44:09 +0200 Message-ID: <87d0i9gfme.fsf@elephly.net> References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:470:142:3::10]:41146) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hngTz-0003dD-2a for guix-devel@gnu.org; Wed, 17 Jul 2019 05:44:20 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hngTx-0002ho-BA for guix-devel@gnu.org; Wed, 17 Jul 2019 05:44:19 -0400 Received: from sender4-of-o53.zoho.com ([136.143.188.53]:21381) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hngTw-0002gu-6j for guix-devel@gnu.org; Wed, 17 Jul 2019 05:44:17 -0400 In-reply-to: List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: Laura Lazzati Cc: guix-devel@gnu.org Hi Laura, > https://archive.org/details/guix-videos and give feedback here :) I second the praise these videos have received. I=E2=80=99m very happy to = see them close to completion. I haven=E2=80=99t 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=E2=80=99s 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=E2=80=A6 is the script really creating =E2=80=9C=E2=80=9D and then again =E2=80=9C=E2=80=9D? If this has been edited: why? - at 02:15 the way =E2=80=9C# yes=E2=80=9D is input would not work in real = life because =E2=80=9C# yes=E2=80=9D is not =E2=80=9Cyes=E2=80=9D. Is this a limitati= on 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 =E2=80=9Cguix install hello=E2=80= =9D instead of =E2=80=9Cguix package -i hello=E2=80=9D. - 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 =E2=80=9Chttps://guix.gnu.org/manual=E2=80=9D. Here are some comments about 02-everyday-use-part-one: - the command =E2=80=9Cguix package --install hello=E2=80=9D is used, but = =E2=80=9Cguix install hello=E2=80=9D might be better - the output refers to =E2=80=9Cci.guix.info=E2=80=9D, but it should be =E2=80=9Cci.guix.gnu.org=E2=80=9D. - the output is wrapped in an unfortunate place (right before the 100%) - we should replace the long store hashes with =E2=80=9C=E2=80=A6=E2=80=9D = 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 =E2=80=9C2 packages in profile=E2=80=9D,= which are not produced by Guix. - it=E2=80=99s confusing that it mentions =E2=80=9C2 packages=E2=80=9D beca= use we didn=E2=80=99t see anyone install the glibc-locales package. - at 2:58 there are two different fonts in use, but I can=E2=80=99t tell wh= y. The diagram also seems a little confusing to me. If it=E2=80=99s suppose= d 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 =E2=80=9Chttps://guix.gnu.org/manual=E2=80=9D. Some comments about 02-everyday-use-part-two: - at 00:21 you show a URL to the previous video. I=E2=80=99d suggest remov= ing that as the URL is long and might change. - at 00:26 =E2=80=9Cguix pull=E2=80=9D appears twice, which is confusing. = I don=E2=80=99t know what the arrows mean. - at 01:01 I don=E2=80=99t understand why there is an arrow from =E2=80=9CG= arbage collector=E2=80=9D to =E2=80=9Cguix gc=E2=80=9D. 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=E2=80=99t use all ca= ps. I also think it=E2=80=99s a bit =E2=80=A6 odd to self-advertise as =E2= =80=9Ckind=E2=80=9D and =E2=80=9Cwarm=E2=80=9D. (This may be true, but it=E2=80=99s for others to assess.) I would spell= out =E2=80=9CCoC=E2=80=9D 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 =E2=80=9COur website=E2=80=9D from all but the first mention of th= e website. There does not need to be a =E2=80=9Csection indicator=E2=80=9D on every = slide =E2=80=94 the videos are short enough to not need them. - at 2:20 =E2=80=9Csubscribing to a mailman=E2=80=9D sounds unintentionally= funny. I=E2=80=99d probably turn that into =E2=80=9CMailing lists=E2=80=9D or skip the heade= r completely. - at 3:05 same comment about the slide being a bit stuffed. There=E2=80=99= 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