Re: We need your feedback of the documentation videos!

[Tobias Geerinckx-Rice]

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.

03-help:
- 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 http://guix.gnu.org/help/ has changed. 
 http://guix.gnu.org/contact/ 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 logs.guix.gnu.org, 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.

04-packaging-part-one:
- 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>

04-packaging-part-two:
The file names should sort spontaneously, for examply by using 
digits: 04-packaging-part-2.  Even if this weren't an issue on 
A/V.gnu.org, 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.

04-packaging-part-three:
- 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.

T G-R

signature.asc
Description: PGP signature