diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index d61da51..8879084 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -37,7 +37,7 @@ Project Publication Depending on the project, your documentation might include some or all of the following components: -- A *introduction* should show a very short overview of what can be +- An *introduction* should show a very short overview of what can be done with the product, using one or two extremely simplified use cases. This is the thirty-second pitch for your project. diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index 51b8105..1fa23e5 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -2,7 +2,7 @@ Common Gotchas ============== For the most part, Python aims to be a clean and consistent language that -avoid surprises, but there are a few cases where newcomers to the language +avoids surprises, but there are a few cases where newcomers to the language often get tripped up. Some of these are intentional but potentially surprising. Some could arguably diff --git a/docs/writing/reading.rst b/docs/writing/reading.rst index 4ab1ddb..8d1e816 100644 --- a/docs/writing/reading.rst +++ b/docs/writing/reading.rst @@ -9,7 +9,7 @@ One of the secrets of becoming a great Python programmer is to read, understand, and comprehend excellent code. Excellent code typically follows the guidelines outlined in :ref:`code_style`, -and does its best to express a clear and consise intent to the reader. +and does its best to express a clear and concise intent to the reader. Included below is a list of recommended Python projects for reading. Each of these projects are paragons of excellent Python code. @@ -41,4 +41,4 @@ these projects are paragons of excellent Python code. .. todo:: Include code examples of exemplary code from each of the projects listed. Explain why it is excellent code. Use complex examples. -.. todo:: Explain techniques to rapidly identify data structures, algorithms and determine what the code is doing. \ No newline at end of file +.. todo:: Explain techniques to rapidly identify data structures, algorithms and determine what the code is doing. diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 919d3a1..6148176 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -109,7 +109,7 @@ passed another value. Calling a function with keyword arguments can be done in multiple ways in Python, for example it is possible to follow the order of arguments in the definition without explicitly naming the arguments, like in ``send('Hello', 'World', 'Cthulhu', 'God')``, -sending a blank carbon copy to God. It would also be possible to name arguments in +sending a blind carbon copy to God. It would also be possible to name arguments in another order, like in ``send('Hello again', 'World', bcc='God', cc='Cthulhu')``. Those two possibilities are better avoided without any strong reason to not follow the syntax that is the closest to the function definition: ``send('Hello', @@ -140,9 +140,9 @@ any sequence, including iterators, that cannot be unpacked as other sequences. The **arbitrary keyword argument dictionary** is the last way to pass arguments to functions. If the function requires an undetermined series of named -arguments, it is possible to used the ``**kwargs`` construct. In the function +arguments, it is possible to use the ``**kwargs`` construct. In the function body, ``kwargs`` will be a dictionary of all the passed named arguments that -have not been caught be other keyword argument in the function signature. +have not been caught by other keyword arguments in the function signature. The same caution as in the case of *arbitrary argument list* is necessary, for similar reasons: these powerful techniques are to be used when there is a @@ -576,7 +576,7 @@ Line Continuations When a logical line of code is longer than the accepted limit, you need to split it over multiple physical lines. Python interpreter will join consecutive lines if the last character of the line is a backslash. This is helpful -sometime but is preferably avoided, because of its fragility: a white space +sometimes but is preferably avoided, because of its fragility: a white space added to the end of the line, after the backslash, will break the code and may have unexpected results. diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index d70d613..70c08f5 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -20,7 +20,7 @@ Some general rules of testing: - Try hard to make tests that run fast. If one single test needs more than a few millisecond to run, development will be slowed down or the tests will not - be run as often as desirable. In some cases, test can't be fast because they + be run as often as desirable. In some cases, tests can't be fast because they need a complex data structure to work on, and this data structure must be loaded every time the test runs. Keep these heavier tests in a separate test suite that is run by some scheduled task, and run all other tests as often @@ -34,10 +34,10 @@ Some general rules of testing: after. This will give you more confidence that you did not break anything in the rest of the code. -- It is a good idea to implement a hook that runs all test before pushing code +- It is a good idea to implement a hook that runs all tests before pushing code to a shared repository. -- If you are in the middle of a development and have to interrupt your work, it +- If you are in the middle of a development session and have to interrupt your work, it is a good idea to write a broken unit test about what you want to develop next. When coming back to work, you will have a pointer to where you were and get faster on tracks.