Minor modifications to the tutorial, mainly english aesthetics

[facundofc]

Lots are trivial things, but even though English is not my native language, I humbly beleive it's a bit better now.

[coveralls]

Coverage remained the same at 99.026% when pulling 4f2d70e on facundofc:tutorial_1_fixes into 0fc00d5 on pydoit:master.

[schettino72]

Thank you so much for this. Very nice to get throughout review.
I agree that all your changes improve the text.
I just have a few comments regarding terminology when related to doit.

Feel free to add your name to AUTHORS file. I think you deserve some credit :)

[schettino72]

I dont like the "default action" because it might be confused with the term action as used in doit tasks. So I would stick with the word execute here, as it is terminology used for programs...

But I agree the paragraph can still be improved. What about:

doit comes with a command line tool to act upon the set of tasks defined in a specific file. The default is a file named dodo.py in the current directory. Without any arguments the command line program executes the all tasks from it.

[schettino72]

Can you still include the parameter name, like:

get_imports takes the path's module as a parameter (module_path).

[schettino72]

Here I have not introduced it here, but a doit task might have an attribute called basename.
So I would like to keep consistent with doit terminology.
I suggest we use your alteration but still mentions "basename", something like:

Note the task name is composed by the task's group name (also known as basename).

[schettino72]

Also interested to get feedback about the tutorial itself (as being an introduction to the tool).
So please let me know what you think about it.

[facundofc]

Thank you so much for this. Very nice to get throughout review.
I agree that all your changes improve the text.
I just have a few comments regarding terminology when related to doit.

Feel free to add your name to AUTHORS file. I think you deserve some credit :)

Hey man! Thanks a lot for the nice feedback, it's really encouraging. Just wanted you to know I'll work on the changes you proposed, just give me some time.

[facundofc]

Also interested to get feedback about the tutorial itself (as being an introduction to the tool).
So please let me know what you think about it.

I think the tutorial is well intended, but is still missing some love. On occasions it sounds like a list of steps, too recipe-like. I would try to give it a more personal touch, like if you were talking to the reader (this is, of course, just a matter of personal taste).

I don't know if you considered it or not, but perhaps it would be nice to pour in some comparisons with make, for the (potentially large) group of users that already know make and are learning doit. It's always nice to have a baseline you can hold on to and then take note of the differences/similarities. Maybe this could be implemented as some "If you know make" notes spread through the document.

A bit more motivation at the beginning would be appropriate too. Not regarding why you'd like to make an imports' dependency graph, but why would you do it using doit. I think this would be very similar to the Use Cases section (to some extent), but phrased different and intended for the users that directly skip to the tutorial.

That's all I can think of at the moment. If you agree on some of these, I volunteer to start making those changes. Just let me know.

Cheers.

[schettino72]

On occasions it sounds like a list of steps, too recipe-like.

Agree, my writing style is very boring 😬
Would be nice to improve it to something more engaging.
Sometime I try but always think it sounds too cheesy and then I go back to my boring style. hehehehe

I don't know if you considered it or not, but perhaps it would be nice to pour in some comparisons with make,

I have considered this. The problem is that it adds noise to people who do not know make.
And most people who "knows" make actually never wrote a Makefile, they just know they have to execute make when compiling some code. I got thousands of people who ask me why they would need doit if python does not need compilation... And for people who actually understand make IMO would be easy for then to draw some comparisons. For those, maybe what would help is to point where doit is actually different from make.

So in general I am bit sceptic that this would be an improvement to write much in comparison to make. I think 2 or 3 notes regarding its differences might be ok.

I think this would be very similar to the Use Cases section (to some extent), but phrased different and intended for the users that directly skip to the tutorial.

I try to not repeat much content, specially introduction, I am afraid to bore people who actually read the stuff... I mean I get annoyed when some docs keeps claiming the same thing but doesnt go into the HOW.

Actually when I wrote the tutorial I pretty much plan it based on the list of use-cases.
Maybe we could be more explicit about how each step correlates to a use-case.

That's all I can think of at the moment. If you agree on some of these, I volunteer to start making those changes. Just let me know.

Thanks so much. In general I agree with the changes but see a few concerns above.
I guess I am receptive to changes but hard to say 100% before it is done.

Note that the tutorial is kind of new compared to the main documentation, the use-case section was not written by me. Of course improvements in any area are welcome...

cheers