Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Minor modifications to the tutorial, mainly english aesthetics #284

Merged
merged 2 commits into from Mar 18, 2019

Conversation

Projects
None yet
3 participants
@facundofc
Copy link
Contributor

facundofc commented Mar 12, 2019

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

@coveralls

This comment has been minimized.

Copy link

coveralls commented Mar 12, 2019

Coverage Status

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

@schettino72
Copy link
Member

schettino72 left a comment

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 :)



task execution
--------------

``doit`` command line by default will execute all tasks defined in ``dodo.py`` module in the current directory.
``doit`` comes with a command line tool to act upon the set of tasks defined in a specific file. The default file is ``dodo.py`` in the current directory, and the default action is to execute all found tasks.

This comment has been minimized.

@schettino72

schettino72 Mar 13, 2019

Member

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.


Note that the parameter ``module_path`` is passed into task definition of ``actions``.
Instead of just specifying a callable it takes a tuple *(callable, args, kwargs)*.
``get_imports`` takes the path's module as a parameter. The value of this parameter to be used upon task execution is specified in the ``actions`` of the task definition. Generally speaking, each element of the ``actions`` array is a tuple *(callable, args, kwargs)*.

This comment has been minimized.

@schettino72

schettino72 Mar 13, 2019

Member

Can you still include the parameter name, like:

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

@@ -596,10 +600,10 @@ Sub-tasks (items of task group) by default are not reported on ``list`` command.
imports:requests.utils


Note the task name is composed by the (base name) group task name

This comment has been minimized.

@schettino72

schettino72 Mar 13, 2019

Member

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

This comment has been minimized.

Copy link
Member

schettino72 commented Mar 13, 2019

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

This comment has been minimized.

Copy link
Contributor Author

facundofc commented Mar 15, 2019

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

This comment has been minimized.

Copy link
Contributor Author

facundofc commented Mar 17, 2019

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 schettino72 merged commit 5002b15 into pydoit:master Mar 18, 2019

3 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
coverage/coveralls Coverage remained the same at 99.026%
Details
@schettino72

This comment has been minimized.

Copy link
Member

schettino72 commented Mar 18, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.