Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.
Sign upTutorial: first example code is very unclear and confusing #1039
Comments
|
Same issues here. In generall the documentation is more confussing than it helps. |
|
There can only be agreement on this, as the tutorial section prefers correctness and testability over being easy to follow. Most certainly the intend of it should be made clearer to set expectations. Since you have been bitten by this and certainly an opinion, I would be happy to see a PR with adjustment that you would have wanted the first time around. It probably won't take much to at least set expectations, without needing to modify the way it's done as this would be way more work that I don't expect anyone to do really. Thanks for your consideration. |
|
Hi Byron, thank you for your reaction. However, I do not think you understand my situation as a reader. I read the tutorial, and get confused by it. Obviously, this means I do not understand much about GitPython. That is the reason I am reading the tutorial. And yet you suggest I send you a PR with how the tutorial should have been written. How do you think I can do this? I am not capable of writing a tutorial for GitPython! If I was, I wouldn't need one... All I can do, is report that it is not understandable for someone who needs a tutorial. Sometimes expecting people who report problems, also to give you the solution, goes a bit too far! |
|
So maybe this is the solution: Change the headline from something including the word 'Tutorial' to something that makes clear what it is: A tour through the major bits of the API using a test suite. When asking for a contribution, I was trying to ask for any adjustment that makes it easier to understand what it is that you are looking at. "… without needing to modify the way it's done as this would be way more work that I don't expect anyone to do really." tries to make clear that this should not be major alteration of the 'tutorial', but some added context to prepare people for what's to expect. Since you explicitly point out a passage that can be perceived as ironic, fixing that one seems like a simple way to leave this place better than you found it. |
The first example code in the tutorial is very unclear:
To start with, this just gives me the error message
NameError: name 'self' is not definedThe comment "rorepo is a Repo instance pointing to the git-python repository" doesn't help. Does this mean "rorepo" is just an example word, and I have to replace it with something from my own system? Does this reference a directory or a repository name I should create on my filesystem? The term "rorepo" doesn't come up any other places in the whole documentation.
Also the following text is only adding to the confusion. "In the above example, the directory self.rorepo.working_tree_dir equals /Users/mtrier/Development/git-python ..." NOT IT DOESN'T. Maybe it does on the specific system for the documentation writer, but it is not a general rule.
The use of "For all you know..." is very ironic here; this expression literally means that the "you" (the reader) doesn't know what the writer wants...
Please modify the tutorial code to apply to general users. if code requires previous actions/setup, then please specify this.