Re: Tutorial length. The Parallel Book

[Gilles LAMIRAL]

Hi Ole,

I give some comments about the Parallel Book

Title
Maybe remove "2018", next years will come sooner than expected.
Suggestion: "The GNU Parallel Book"

About the reading levels : 5 levels looks too much,
just 2 or 3 levels at max is simpler for the reader and for you the writer.

* level 1: for beginners & basic users. One bar |
* level 2: for advanced users. Two bars ||
* level 3: for hardcore, source code users. |||

Another point, the system bar, if any, should be self-evident.
The current five levels system is not self-evident at all,
I see 2 bars, it means level 2, but no: it's level 5 indeed.
I see 1 bar, well, it's what level actually?

The initial tour, chapter 2, at level 1 only, is a very good thing,
it's the tutorial for beginners I need when I start using a tool.

The other chapters are also well classified. But instead of
mixing level 1 and level x several times in the same chapter,
starting with level 1 and increasing difficulties to next level
could bring an easier way to learn and master Parallel.

The constant questions the reader asks himself are:
 * "Where am I?"
 * "Should I skip what I'm reading? Will I miss something relevant?"


Initial tour of 5 minutes

Ole, it took me 25 minutes to read and apply this initial "5 minutes" chapter 2.
I used copy/paste for the examples and I was already familiar with parallel.
Those 25 minutes don't include the comments I'm writing now.

2.1 Input sources

The sentence "The values are put after ::: :" is very ambiguous!
Is it a typo? 3 ::: or 4 :::: (I do understand what the last is but
it is not a good punctuation character in the Parallel context.

2.2 Building the command line

Typo: "It can contain contain a command"

Another ambiguous sentence due to punctuation mark:
"The command line is put before the :::."

Suggestion: The command line is put before the three consecutive colons ::: 
characters.


 --dry-run could be called --dry (I'm lazy)

 2.4 Controlling the execution

 For the -j parameter, instead of the wget, I suggest to test two
 similar commands

   parallel -j2   sleep {}';' echo {} done :::  5 4 3 2 1 6 7 8 9 2 2 1 0

   parallel -j20  sleep {}';' echo {} done :::  5 4 3 2 1 6 7 8 9 2 2 1 0

The second demonstrates what happens when all sleep commands are launched
in parallel, all the "sleep x" finish at the nearly same time, after x seconds.
The first demonstrates the sequential behavior forced by the "2 runs at the 
time"
restriction.

Of course, that's just suggestion, you're the master!


Le 11/01/2018 à 03:01, Ole Tange a écrit :

> So I have started writing the 'GNU Parallel 2018'-book. The first
> version I tried doing as you suggest, but it really did not work well
> for me: Depending on your situation you need to dive deep into one
> concept without having to know much about the other concepts (e.g.
> maybe outputting to CSV is key for you, but the rest of the default
> settings are fine).

This suggests that 2 levels are enough.

> The concepts hardly overlap, thus it will make perfect sense to be an
> expert in output-options without knowing more than the basics about
> remote execution.

This reinforces that 2 levels are enough.
Let the reader decides what level is his for any part,
once he's no longer a beginner, he is an advanced user for that part.

> So instead I have tried dividing the book in parallel: So each section
> has all information in all details, but the margin has a legend that
> tells you how advanced the paragraph is. Thus you are encouraged to
> skip to the next paragraph at your reader level.
>
> The book is heavily based on parallel_tutorial.
>
> I welcome reader's feedback on it. I have uploaded the current
> (extremely incomplete) draft at
> https:://hushfile.it/5a56c3d63d853#nDpLjkqxFB_K3SKjgIm6BBpLuzjOFY_Yfw6mfx0W
> Open in LibreOffice.
>
> Most important feed back would be: Does this marking of the reader
> level in the margin work?

Not well for me, as explained above.

Well chosen examples are also keys to understand a concept,
I'll try to give the ones that make sense to me while
I learn parallel.



--
Au revoir,
Gilles Lamiral. France, Baulon (35580)
mob 06 19 22 03 54
tel 09 51 84 42 42