Footnotes¶

Footnotes are generally discouraged, though they may be used when they are thebest way to present specific information. When a footnote reference is added atthe end of the sentence, it should follow the sentence-ending punctuation. ThereST markup should appear something like this:

This sentence has a footnote reference.[#]_ This is the next sentence.

Footnotes should be gathered at the end of a file, or if the file is very long,at the end of a section. The docutils will automatically create backlinks tothe footnote reference.

Footnotes may appear in the middle of sentences where appropriate.

Capitalization¶

Many special names are used in the Python documentation, including the names ofoperating systems, programming languages, standards bodies, and the like. Mostof these entities are not assigned any special markup, but the preferredspellings are given inSpecific words to aid authors in maintaining theconsistency of presentation in the Python documentation.

Specific words¶

Some terms and words deserve special mention. These conventions shouldbe used to ensure consistency throughout the documentation:

C API

Python’sAPI used by C programmersto write extension modules. All caps and unhyphenated.

CPU

Central processing unit. No need to spell out.

POSIX

The name assigned to a particular group of standards. This is alwaysuppercase.

Python

The name of our favorite programming language is always capitalized.

reST

For “reStructuredText,” an easy to read, plaintext markup syntaxused to produce Python documentation. When spelled out, it isalways one word and both forms start with a lowercase ‘r’.

time zone

When referring to a Python term like a module, class, or argument spell itas one word with appropriate markup (for example,:mod:`timezone`).When talking about the real-world concept spell it as two words with nomarkup.

Unicode

The name of a character coding system. This is always writtencapitalized.

Unix

The name of the operating system developed at AT&T Bell Labs in the early1970s.

Use simple language¶

Avoid esoteric phrasing where possible. Our audience is world-wide and may notbe native English speakers.

Don’t use Latin abbreviations like “e.g.” or “i.e.” where English words will do,such as “for example” or “that is.”

Diátaxis¶

Python’s documentation strives to follow theDiátaxisframework. This means adapting the writing style according to the nature ofthe documentation that is being written. The framework splitsdocumentation into four distinct types: tutorials, how-to guides, reference, andexplanation.

• The Python Tutorial shouldbe explicit and avoid making assumptions about thereader’s knowledge. The goal of a tutorial is to get the user writingPython code as quickly as possible with clear logical steps. Explanationsand abstract concepts should be avoided. Please consult the Diátaxis guide onTutorials for more detail.

• Python how-to guides aredesigned to guide a user through a problem-field.Both tutorials and how-to guides are instructional rather than explanatoryand should provide logical steps on how to complete a task. However,how-to guides make more assumptions about the user’s knowledge andfocus on the user finding the best way to solve their ownparticular problem.

• The Python Language Reference shouldbe factual and succinct. The purpose of reference documentation isto describe rather than to explain. Accuracy and consistency are key asthis type of documentation should be seen as an authoritative source.Code examples can be a useful way of achieving theseobjectives.

• Python explanations providea deeper level of understanding and are naturally more discursive. They aimto deepen the reader’s understanding and answer ‘why’ questions. They shouldprovide context, make connections between topics, and discuss alternativeopinions. There is no section dedicated to explanations but these can befound throughout Python’s documentation, for example theUnicode HOWTO.

Please consult theDiátaxis guide for moredetail.

Links¶

Links are a powerful tool for helping people navigate documentation and findmore information, but links can be over-used. Links should be used only ifthey help the reader.

Generally, a link should be provided for the first use of a term in a unit,such as a section or paragraph. This is not a hard and fast rule. Sometimesthe second mention is more appropriate for a link. Some units are long enoughto have a few repeated links. Use judgement to decide when a link will helpthe reader.

Do not use a link when the link would point to the current unit. It’s naturalto use the name of a function in the documentation for the function, but a linkon that function name that simply reloads the section the user is alreadyreading is useless and distracting.

Do not use links in section headers. They distract from the title of thesection. The term will be mentioned in the paragraph text and can be linkedfrom there.

Sphinx provides ways to automatically add links to references, and a way tosuppress the link. Using roles like:func:`map` will link to thedocumentation formap. You can suppress the link while keeping thesemantic presentation of the function name by adding an exclamation pointprefix::func:`!map`. SeeRoles for more details.

Affirmative tone¶

The documentation focuses on affirmatively stating what the language does andhow to use it effectively.

Except for certain security or segfault risks, the docs should avoidwording along the lines of “feature x is dangerous” or “experts only”. Thesekinds of value judgments belong in external blogs and wikis, not in the coredocumentation.

Bad example (creating worry in the mind of a reader):

Warning: failing to explicitly close a file could result in lost data orexcessive resource consumption. Never rely on reference counting toautomatically close a file.

Good example (establishing confident knowledge in the effective use of thelanguage):

A best practice for using files is use a try/finally pair to explicitlyclose a file after it is used. Alternatively, using a with-statement canachieve the same effect. This assures that files are flushed and filedescriptor resources are released in a timely manner.

Author attribution¶

For new documentation, do not use a byline (naming the author of the document).Explicit attribution tends to discourage other users from updating communitydocumentation.

Existing documentation with bylines will not be changed unless the authordecides to do so. This is subject to change in the future.

Pronunciation of dunder names¶

“Dunder names” like__init__ can be awkward in running prose: is it “aninit” or “a dunder init”? Our recommendation is to ignore the underscores anduse the article that is appropriate for the word in the name. Aquick pollbacks this up: “an __init__.”

Economy of expression¶

More documentation is not necessarily better documentation. Err on the sideof being succinct.

It is an unfortunate fact that making documentation longer can be an impedimentto understanding and can result in even more ways to misread or misinterpret thetext. Long descriptions full of corner cases and caveats can create theimpression that a function is more complex or harder to use than it actually is.

Security considerations (and other concerns)¶

Some modules provided with Python are inherently exposed to security issues(for example, shell injection vulnerabilities) due to the purpose of the module(for example,ssl). Littering the documentation of these modules with redwarning boxes for problems that are due to the task at hand, rather thanspecifically to Python’s support for that task, doesn’t make for a goodreading experience.

Instead, these security concerns should be gathered into a dedicated“Security Considerations” section within the module’s documentation, andcross-referenced from the documentation of affected interfaces with a notesimilar to"Pleaserefertothe:ref:`security-considerations`sectionforimportantinformationonhowtoavoidcommonmistakes.".

Similarly, if there is a common error that affects many interfaces in amodule (for example, OS level pipe buffers filling up and stalling child processes),these can be documented in a “Common Errors” section and cross-referencedrather than repeated for every affected interface.

Code examples¶

Short code examples can be a useful adjunct to understanding. Readers can oftengrasp a simple example more quickly than they can digest a formal description inprose.

People learn faster with concrete, motivating examples that match the context ofa typical use case. For instance, thestr.rpartition() method is betterdemonstrated with an example splitting the domain from a URL than it would bewith an example of removing the last word from a line of Monty Python dialog.

The ellipsis for thesys.ps2 secondary interpreter prompt should onlybe used sparingly, where it is necessary to clearly differentiate between inputlines and output lines. Besides contributing visual clutter, it makes itdifficult for readers to cut-and-paste examples so they can experiment withvariations.

Code equivalents¶

Giving pure Python code equivalents (or approximate equivalents) can be a usefuladjunct to a prose description. A documenter should carefully weigh whether thecode equivalent adds value.

A good example is the code equivalent forall(). The short 4-line codeequivalent is easily digested; it re-emphasizes the early-out behavior; and itclarifies the handling of the corner-case where the iterable is empty. Inaddition, it serves as a model for people wanting to implement a commonlyrequested alternative whereall() would return the specific objectevaluating to False whenever the function terminates early.

A more questionable example is the code foritertools.groupby(). Its codeequivalent borders on being too complex to be a quick aid to understanding.Despite its complexity, the code equivalent was kept because it serves as amodel to alternative implementations and because the operation of the “grouper”is more easily shown in code than in English prose.

An example of when not to use a code equivalent is for theoct() function.The exact steps in converting a number to octal doesn’t add value for a usertrying to learn what the function does.

Audience¶

The tone of the tutorial (and all the docs) needs to be respectful of thereader’s intelligence. Don’t presume that the readers are stupid. Lay out therelevant information, show motivating use cases, provide glossary links, and doyour best to connect-the-dots, but don’t talk down to them or waste their time.

The tutorial is meant for newcomers, many of whom will be using the tutorial toevaluate the language as a whole. The experience needs to be positive and notleave the reader with worries that something bad will happen if they make amisstep. The tutorial serves as guide for intelligent and curious readers,saving details for the how-to guides and other sources.

Be careful accepting requests for documentation changes from the rare but vocalcategory of reader who is looking for vindication for one of their programmingerrors (“I made a mistake, therefore the docs must be wrong …”). Typically,the documentation wasn’t consulted until after the error was made. It isunfortunate, but typically no documentation edit would have saved the user frommaking false assumptions about the language (“I was surprised by …”).

Function signatures¶

These are the evolving guidelines for how to include function signatures in thereference guide. As outlined inDiátaxis, reference material shouldprioritize precision and completeness.

• If a function accepts positional-only or keyword-only arguments, include theslash and the star in the signature as appropriate:

  ..function:: some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

  Although the syntax is terse, it is precise about the allowable ways to callthe function and is taken from Python itself.