Currently, HOWTO docs vary from document to document about whether the content is how-to directions, explanations, or a combination of both.

This confuses readers on whether they will find steps to achieve a task or an in-depth explanation of a topic. For documentarians, this makes it difficult to determine how to update these documents, the best way to communicate their contents, and how/if to keep them useful to the reader.

Background

The introductory description of the Python HOWTOs section explains that the HOWTO docs were inspired by the Linux HOWTO docs. The Linux HOWTO docs were a combination of explanations and step-by-step instructions.

Some of the Linux HOWTO docs (https://tldp.org/HOWTO/HOWTO-INDEX/howtos.html have been spun out of the kernel documentation (docs.kernel.org). The majority of the documents on tldp.org have not been updated since 2015.

Diataxis - How-to vs. Explanation

In the Diataxis approach to documentation, How-to documents have a different purpose than the original Linux HOWTO docs.

How-to guides are directions that guide the reader through a problem or toward a result. How-to guides are goal-oriented.

Explanation documents have a purpose that better aligns with the majority of existing HOWTO documents.

Explanation is a discursive treatment of a subject, that permits reflection. Explanation is understanding-oriented.

Possible next steps

Short term

1. Provide a better introductory description of the Python HOWTO documentation.
2. For each document, surface a last updated date and a created date.
3. Provide a table contents alphabetically and by last updated date.

Longer term

The @python/editorial-board working with the documentation community should look to reduce the confusion for readers and documentarians.