Grammar and Mechanics

Grammar and mechanics is an essential part of writing clear content. In this document, we've laid out our guidelines for grammar, mechanics, writing style, and content formatting so that readers of Kite Answers can have a unified and high-quality reading experience with each article.

Guidelines

Adverbs

Adverbs are words that modify verbs, adjectives, or other adverbs. Adverbs often contribute nothing.

Common offenders include:

• simply
• easily
• just
• very
• really
• basically
• extremely
• actually

Examples

To open the file, simply click the button.

To open the file, click the button.

You can easily edit the form by...

To edit the form...

American spelling and grammar

Whenever U.S. English and British (or other) English spelling or usage disagree, standard U.S. spelling and usage is preferred.

Examples

The colour of the button is grey.

The color of the button is gray.

Capitalization

Answer titles and section titles should be in Sentence case. Only the first word should be capitalized, along with any proper nouns or other words usually capitalized in a sentence.

Code elements (inline)

This section describes inline code elements (which appear like this). For instructions on code blocks see the Code Style Guide.

Wrap inline code snippets in backticks and use the appropriate capitalization.

The `pop()` function removes the item...

For many code elements, this will mean not capitalizing the code element, even if the name of the code element starts a sentence.

Examples

Remove() removes the first matching value from the list.

remove() removes the first matching value from the list.

For other code elements, this will mean deliberately capitalizing the code element. If you're unsure, check the official docs to see whether the element is capitalized or not capitalized when used in code.

Examples

How to sort a dataframe

How to sort a `DataFrame`

Also use backticks around built-in types like int, float, and string.

Don't use backticks when referring to concepts

Sometimes code elements are named after the concept they represent, like datetime.date and datetime.time. In these cases it can be hard to know when you should use backticks or not.

Use backticks only when you're referring specifically to a code element.

Examples

Converting a `datetime` object to a `date` removes the `time` information.

Converting a `datetime` object to a `date` removes the time information.

In this example, the datetime and date words are referring to code elements, whereas the "time" word is referring to the concept. Therefore datetime and date should be surrounded by backticks and "time" should be normal text.

The same rules apply when deciding whether to surround literals (e.g. numbers and strings) in backticks. When referring to a literal from an example, ask yourself if you are referring to the code element.

Examples

`datetime()` returns a `datetime` object set to the year 2010 because we passed in `2010` as the first parameter.

Sometimes it can be ambiguous whether to use backticks. For example, in "Use string slicing to reverse a string" the last word could plausibly refer to string as a concept or string as an object. In such cases, prefer referring to string as a concept, without backticks. The thinking is that inline code spans demand more of the reader, so we choose the style that is lighterweight.

Use () when referring to a function

If you refer to a function, always include at least () at the end, including in headings.

Include the relevant signature of a function the first time you refer to it

For example, isinstance(object, classinfo). When present and you are using them, include keyword arguments, *args, **kwargs, and default values in the signature.

If you use a keyword argument in one example, but not another, specify the signature to inclue the keyword argument wherever it is used.

Examples

The example below is wrong because it refers to a different form of the function signature than what is called.

Use the `range(start, stop, step)` function...

range(0, 5)

Refer to the signature you're using instead.

Use the `range(start, stop)` function...

range(0, 5)

Use the `range(start, stop, step)` function...

range(0, 5, 2)

There are various ways you can find the names of parameters. The easiest way to find the official signature for a function is to run the help() function from a Python REPL.

Examples

>>> help(range)
Help on class range in module builtins:

class range(object)
|  range(stop) -> range object
|  range(start, stop[, step]) -> range object
|  
|  Return an object...

Note that "official signatures" can vary widely from what is used, and we only care about what's used.

For example, the official signature for matplotlib.pyplot.plot() is plot(*args, scalex=True, scaley=True, data=None, **kwargs). If we are calling the function by passing in an x and a y, use plot(x, y) in your text because it's the clearest, even though those parameters are passed in via *args and aren't named in the official signature.

Omit all arguments you aren't using, including positional args, keyword args, and kwarg parameters. For example, if your answer uses range() with two parameters, but not the third, refer to range(start, stop) instead of range(start, stop, step).

Any answer referring to a function should include each signature at least the first time it is referenced. But don't refer to a full signature in headings. Therefore, any answer referring to a function in a heading must refer to it at least once in text, so the signature can be included.

If you are not familiar with all the moving pieces of function call parameters in Python, read about them online. (Here is one quick Google result, although there may be better ones out there.) You should how positional arguments, varargs, keyword arguments, and kwargs all work together.

Functions with multiple signatures

Some functions have multiple possible signatures. For example range() has both range(stop) and range(start, stop, step). Include the signature you are using in your answer.

If you use both forms in your answer, introduce them separately. For example, introduce range(stop) the first time you use it, and then introduce range(start, stop, step) when you use it. Make sure all abbreviated references to range() are clear.

Do not try to combine multiple signatures into one. For example, do not write range([start], stop[, step]) even though it is semantically equivalent to the two actual signatures, because it adds confusion.

Including fully qualified module and class names

There are multiple parts to a fully qualified e.g. method like pandas.DataFrame.from_csv(). In this example...

• pandas is the module. Module names can include multiple parts such as django.contrib.auth.models.
• DataFrame is a class name.
• to_csv() is a function name. It can also be called a method because it's a function that belongs to an class. It can also be called an attribute, which is anything that is accessed using a .. (An attribute could also be, for example, a field.)

This guideline describes what level of detail to include when referring to something in Python. Follow these rules, listed in order of priority.

1. When referring to a code element in a heading, use only the attribute name, i.e. what is on the far-most right hand side.

Examples

How to `remove()` an item from a list in Python.

1. If not in a title, use the fully qualified version in the first mention.

Examples

Use `pandas.DataFrame.to_csv()`.

This rule also applies to references to classes.

Examples

Use a `pandas.DataFrame` to hold your data.

1. If an attribute of an object has been used, use the <object>.<attribute> format for other attributes of the same object when those attributes appear for the first time. This does not apply to mentions of an object without a specific attribute attached.

Examples

Use `pandas.DataFrame.read_csv()` to create a `DataFrame` from a CSV file. Use `pandas.DataFrame.to_csv()` to save a `DataFrame` as a CSV file.

Use `pandas.DataFrame.read_csv()` to create a `DataFrame` from a CSV file. Use `to_csv()` to save a `DataFrame` as a CSV file.

Use `pandas.DataFrame.read_csv()` to create a `DataFrame` from a CSV file. Use `DataFrame.to_csv()` to save a `DataFrame` as a CSV file.

Once an object has been referenced in a fully qualified way, don't refer to it fully qualified. In the example below, the first reference to DataFrame should be fully qualified.

Examples

To create a `DataFrame` from a CSV file, use `DataFrame.read_csv()`.

To create a `pandas.DataFrame` from a CSV file, use `DataFrame.read_csv()`.

1. Use only the attribute name after its first mention.

Examples

The index in `list.pop(ix)` is optional. If no index is specified, `pop()` removes and returns the last item.

Referring to argument names

When refering to an argument, i.e. 'start', 'stop' in range(start, stop), use them as nouns.

Examples

Use `range(start, stop)` with `stop` set as `5`.

Use `range(start, stop)` with the `stop` parameter set as `5`.

Link code identifiers to their Kite documentation using kite-sym

When referencing a code element from the open source world, link to its documentation using this syntax:

[`date()`](kite-sym:datetime.datetime.date)

The preview tool will show you inline code spans that aren't linked in red. Not every code span should be linked, for example if you are referring to a number like 0.

Links also appear in red when you wrote a kite-sym link but it doesn't resolve to a page in Kite's documentation corpus. If this happens make sure you're using the fully qualified path, for example datetime.datetime.now not datetime.now.

Use inline text for file extensions

When refering to a file with a specific extension, place the extension, including a period, in inline text at the start.

Examples

Use `pandas.read_csv()` to read a `.csv` file. 

Use `pandas.read_csv()` to read a CSV file. 

Do not use inline text in the title, instead capitalize the extension.

Examples

How to read a CSV file in Python

How to read a `.csv` file in Python

It is at your discretion whether or not to include the word "file" after the file extension, both in the title and the main text.

To link to built-in Python classes, use kite-sym:builtins

Reference built-in classes (tuple, int, list, etc...) via the builtins prefix:

[`list()`](kite-sym:builtins.list)

Warning: __builtin__ references the Python2 docs, versus builtins which is the Python3 version. Please use the Python3 version unless an answer specifically requires Python2.

Etc.

Et cetera (or etc.) deserves a special mention.

Et cetera means "and all the rest," and is often used to indicate that more that could be said which is being omitted.

Writers often use etc. to gloss over details of a subject which they are not fully aware of. If you find yourself tempted use etc., ask yourself if you really understand the thing you are writing about.

Filler words and phrases

Many words and phrases provide no direct meaning. They are often inserted to make a sentence seem more formal, or to simulate a perceived style of business communication.

These should be removed.

Common filler phrases and words include:

• to the extent that
• for all intents and purposes
• when all is said and done
• from the perspective of
• point in time
• as you can see
• essentially
• basically

This list is exemplary, not exhaustive.

These phrases, and others like them are pervasive in technical writing.

Remove them whenever they occur.

"...in Python"

In almost all cases, only reference "...in Python" in the title of an answer. Don't add it to the end of arbitrary solution headings or sentences.

Latin abbreviations

Several Latin abbreviations are common in written English:

• e.g.
• i.e.
• vis-a-vis
• cf.
• etc.
• ibid.
• vs.

These present a barrier to understanding, and are often misused by writers.

Examples

Avoid Latin abbreviations.

If you need to operate on a list (e.g., transform all the element)...

If you need to operate on a list (for example, transform all the element)...

Libraries

Refer to libraries using their official capitalization

Usually only the first letter is capitalized. Here are the official capitalizations for several popular libraries:

Examples

• NumPy
• Pandas
• scikit-learn
• Flask
• Django
• TensorFlow
• Matplotlib

Refer to libraries without backticks most of the time

You do not need to use backticks when referring to a library as a concept, but do use backticks when referring to its code embodiment. Prefer referring to the library-as-concept form.

Examples

When using Pandas, ...

Begin by importing `pandas`.

Lists

Avoid complicated serial lists

If your list has more than three items, or if each item is more than one or two words, a bulleted list is often more clear than an inline list.

Even when a list is simple, bulleted lists can still be a more powerful way to communicate technical ideas. There's no hard rule about which to use in any situation, so use your judgement. Try it both ways and see which is more clear.

Examples

You will need to be familiar with git, GitHub, and Python.

You will need to be familiar with:

• git
• GitHub
• Python

Ordered lists

An ordered list is numbered. It should be used when the order of the list is essential. For example, use an ordered list when enumerating a series of steps in a procedure.

Examples

• First we do this.
• And then we do this.
• And then we do this.

1. Do this.
2. Do this.
3. Do this.

Unordered Lists

An unordered list is bulleted. It should be used for a collection of items in which order is not essential.

Examples

1. apples
2. oranges
3. bananas

• apples
• oranges
• bananas

Pronouns

Avoid personal pronouns

Use singular they when needed, but you should not need it often.

Personal pronouns are rarely appropriate to technical writing, which should normally be written in either a descriptive or imperative mode.

Therefore, avoid the use of personal pronouns whenever possible. Rewriting passages to avoid personal pronouns often makes the writing more clear.

Examples

First a developer should write a test. Then they should run the test.

1. Write the test.
2. Run the test.

Third-person personal pronouns

Third-person personal pronouns are:

• he/him/his
• she/her/her(s)
• they/them/their(s)

There are two issues with personal pronouns:

• gender bias
• clarity

Singular they

Some people consider singular they to be non-standard (or "incorrect"). However, it has gained wide use as a gender-neutral or gender-ambiguous alternative to he or she.

In order to avoid gender bias, use singular they instead of gendered pronouns when writing about abstract individuals.

Examples

The user opened his terminal.

The user opened his/her terminal.

The user opened their terminal.

(If you are writing about an actual person, use that person's preferred pronouns if you know them.)

Generic you

Avoid using the generic you because Kite Answers is written formally and answers are cleaner without it. Instead, use the imperative mood.

Examples

If you would like a different start value, you can use range(start, stop).

To specify a different start value, use range(start, stop).

"Same"

Same, when used as an impersonal pronoun, is non-standard in Modern American English.

It should be avoided.

Examples

Python functools is a part of the standard library. The same can be used for...

Python functools is a part of the standard library. It can be used for...

Use the suggested terminology if there is not a more appropriate term

The following are preferred default terms that we would like all code examples to use for general cases. If there is not a better term based on the name of the function, what the documentation indicates, or the SEO keywords, use these.

TO REITERATE, THESE TERMINOLOGY SUGGESTIONS ARE LOWER PRIORITY THAN SEO CONCERNS.

• Use a or an instead of one
• Prefer construct over make, create, return, generate
• Prefer compute over calculate, return
• Prefer convert over map, translate
• Prefer equal over identical
• Prefer hex over hexadecimal
• Prefer get over return, print, show, view, but use more specific words if possible
• Prefer sequence over list, array, iterable
• Prefer item over element, value
• Prefer condition over predicate, if-statement
• Prefer list over iterate, loop over, get an iterable for

Additionally, use the following common terms, even though they are not English words:

• datetime, not date time
• filename, not file name

Use consistent vocabulary for interchangeable object types

For example, use "element" to refer to items of an array. Do not interchange between "element" and "item".

Use terms appropriate for the demonstrated concept

For example, when writing an answer that work with HTTP requests, use "Send a GET/POST/etc. request..." instead of "Request a URL..." or "Make a request...".

Use the articles "a" and "an" for general behavior, and "the" for specific behavior

Examples

print mimetypes.guess_extension("text/html")
print mimetypes.guess_extension("audio/mpeg")
print mimetypes.guess_extension("fake/type")

• Good: "Guess the file extension from a MIME type" - In this example, we are demonstrating that the guess_extension() function will return a specific file extension, and that it works for various MIME types. Therefore, we want to use the definite article "the" to refer to file extensions, and the indefinite article "a" to refer to MIME types.
• Bad: "Guess a file extension from a MIME type" - Implies that we are guessing some file extension, not a specific one
• Bad: "Guess a file extension from the MIME type" - Implies that we are guessing some file extension from a specific MIME type, which is not what the example shows
• Bad: "Guess the file extension from the MIME type" - Implies that we are only demonstrating the function for a specific MIME type, which is not what the example shows

Prefer to use digits rather than spell out numbers

Use your best judgment on whether to use digits/numerals (e.g. 5) or spell out the word of numbers (e.g. five). Some general guidelines:

If a number is a parameter that is core to the example, use digits.

Examples

• Good: "Wrap a string of text to width 30"
• Bad: "Wrap a string of text to width thirty"

If a number expresses something that is typically written with digits (e.g. measurements, dimensions, constants), use digits.

Examples

• Good: "Construct a 3-by-5 identity matrix"
• Bad: "Construct a three-by-five identity matrix"

If a number is none of the above, and is also less than 10, spell it out.

Examples

• Good: "Combine two arrays"
• Bad: "Combine 2 arrays"

When in doubt, use digits.

External links

External links are permitted, but are only appropriate in some rare cases.

Avoid linking from code elements

Our tooling auto-links identifiers to their documentation, so please do not add links inside code elements, inline or otherwise.

Even if our tool doesn't automatically generate a link, it may in the future as we expand its coverage.

If it's August 2019 or thereafter and auto-linking isn't working the way you think it should, please let us know so we can look into it.

Only add links when most readers will find them useful

Each reader who comes across a link needs to look at the link, decide whether or not it may be useful, potentially follow it, and read it. This is a lot of work so only include links that most visitors will find immediately useful to what they're doing.

Background thinking for this rule: * Links are cheaper when it's immediately obvious to the reader what the link is. For example, on Wikipedia if you see a link you know it's to the Wikipedia page for that topic. External links, which are more heterogeneous and more expensive to evaluate, are hidden behind footnotes. (Wikipedia has a good linking strategy!) * Inline links on our pages are cheap if they're to documentation, which is why we have put the work into auto-linking identifiers.

Avoid "the foo() function" and "the foo() method"

Instead of referring to "the foo() function" (or library, class, attribute, method, etc), just refer to foo().

Examples

Call the range(stop) function to...

Call range(stop) to...

This rule applies to functions because the parentheses communicates that you're referring to a function.

This rule does not apply to other kinds of code entities. For example you may wish to refer to "the foo object".

Use the imperative voice to describe function behavior

Use the imperative voice when introducing a solution.

Examples

Call range(stop) to...

Calling range(stop) returns...

range(stop) returns...

However, when explaining the output of a code sample, use the active voice.

Examples

Call range(stop) to get a sequence of consecutive numbers from 0 up to stop. print(range(3)) In this example, calling range(stop) ...

Acronyms

Use acronyms if they are typically used as such; otherwise, spell them out with each word capitalized

Examples

Good:

• HMAC
• CSS
• Recurrent Neural Network
• Daylight Savings Time

Bad:

• LDA (should be Latent Direchlet Allocation)
• RNN (should be Recurrent Neural Network)
• HyperText Markup Language (should be HTML)
• Structured Query Language (should be SQL)

Exceptions:

• use "random number generator", not RNG or Random Number Generator

When in doubt, spell them out.

Capitalize acronyms

For example, "CSV", not "csv".

Punctuation

Commas

In a comma-delineated list of items, the penultimate (second-to-last) item should be followed by a comma. This is known as the serial (or Oxford) comma.

Examples

Apples, oranges and pears.

Apples, oranges, and pears.

Quotation marks

Avoid quote marks

Quote marks are used in prose writing to indicate verbatim text. This is rarely useful in technical writing.

Examples

Click the button that says, "Save."

Click Save.

Straight quotes

Any time that you do need to use quotation marks, use straight (or plain) quotes. Our rendering system will output smart quotes.

Examples

You may see an error message that says, "Something went wrong."

You may get an error: Something went wrong.

Semicolons

Semicolons are used to separate two independent clauses which could stand as individual sentences but which the writer feels would benefit by close proximity.

Semicolons can almost always be replaced with periods (full stops). This rarely diminishes correctness and often improves readability.

Examples

Semicolons can almost always be replaced with periods (full stops); this rarely diminishes correctness and often improves readability.

Semicolons can almost always be replaced with periods (full stops). This rarely diminishes correctness and often improves readability.

Avoid contractions

Examples

• Good: "...should not..."
• Bad: "...shouldn't..."

Try to avoid using the possessive case

Examples

• Good: "...the name of a thread..."
• Bad: "...a thread's name..."

Python = Python 3

All of our examples and explanations use Python 3 by default, without special comment. (Python 3 is just Python.) In the (rare) case that an answer requires a reference to Python 2, put the Python 2 examples after the main examples, and make clear they are a special case.

Spacing

One space between sentences

Use one space between sentences — not two.