[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: We need your feedback of the documentation videos!

From: Tobias Geerinckx-Rice
Subject: Re: We need your feedback of the documentation videos!
Date: Tue, 30 Jul 2019 19:12:50 +0200

Laura, everyone,

More badly-written notes from watching the other half of these fine video shows. I'll try to submit some patches myself, if I manage. Many are just me thinking aloud, not worth delaying a release.

- 00:40 It's a shame that Paul made such a good job of reading our old URL :-( All URLs in this video (and the others; fun!) should be tested for 404s & 308s before releasing the videos, although that's eminently scriptable.

- 01:10 has changed. would now make a better screenshot to match the audio at this timestamp.

- 02:15 Was the title ‘subscribing to a mailman’ intentional? The conventional and boring choice would be ‘mailing list’ or just ‘list’.

- 03:44 We can now add a ‘link’ to, to give new users a sense of the place before they jump in, which can be intimidating. Since this logging is not done by Freenode, I'd move it to the bottom of the slide as its own top-level item.

- 00:13 This slide would be much easier to scan if both the arrows and the commands were vertically aligned. ‘get’ should be capitalised. ‘bootstrap’ is only ever run as ‘./bootstrap’. Let's write ‘./pre-inst-env’ as well since it's not in $PATH.

<nckx cares too much about fonts>
In 02-everyday-use-part-two, commands like ‘guix install’ were set in the highly condensed sans-serif. The serif font used here is a much better choice for commands (and more efficient than monospace). Whatever the choice, I think it should be 100% consistent across videos.
</nckx cares too much about fonts>

The file names should sort spontaneously, for examply by using digits: 04-packaging-part-2. Even if this weren't an issue on A/, people may upload them elsewhere if we're lucky, and 04-packaging-part-three currently plays before this one.

00:30 ‘Using’ → ‘Use’ to match the rest.
‘i.e.’ should be ‘e.g.’, or drop it entirely because:
‘R’ → ‘R packages’. If that really can't be made to fit we'll have to rewrite that; ‘R are’ doesn't work *and* sounds silly.

- 01:15 I'm afraid this could be taken as a joke. Maybe expand the RHS of the ‘algorithm’ to include the steps later covered in part 3? They could be greyed out to show that we'll focus on ‘guix import’ in this video.
More ‘backwards’ font usage: serif text, sans-serif command.

- 02:25 ‘open with a text editor <> file’ → ‘open the <> file with a text editor’. Personally, I'd like to see ‘append alphabetically’ (or ‘add alphabetically’, since ‘append’ can be mistaken to mean ‘at the end’). The audio will still say ‘append’ but that's all right.

- 00:20 The difference between ‘2) Check’ and ‘3) Test’ is not clear to me. The audio doesn't explicitly mention these 4 steps. Using lone imperatives can be powerful, but these just confuse me. *Maybe*: if we chose expand the ‘packaging algorithm’ in part 2, we could re-use that here, with the other half greyed-out. There also appears to be an extra space before Test, but this might not be there in the code.

- 00:55 Apparent extra space before Check (which should be ‘Check for’), same for Gender in the next slide. This always seems to happen on the 3rd item. Coincidence? The font rendering in general is just… off, but that's obviously not your fault.
Typo: ‘Gender-neutral’.
Here, too, I find the ‘random’ arrow positioning and inconsistent spacing (like ‘    etc/’ at 01:50) a bit distracting.

Lists like these always sound so negative.  I love the videos.


Attachment: signature.asc
Description: PGP signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]