Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-1145: Add an overview of Diátaxis to the style guide #1177

Merged
merged 4 commits into from
Feb 6, 2024
Merged

gh-1145: Add an overview of Diátaxis to the style guide #1177

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
89e2af5
Add Diataxis section to style-guide.rst
Jamesgo1 Oct 6, 2023
777e0c2
Implemented changes from review and added Diataxis to intersphinx map…
Jamesgo1 Dec 21, 2023
284e345
Implement Diataxis changes suggested by ezio-melotti
Jamesgo1 Dec 22, 2023
e04805e
Link directly to Diataxis for home page references and add intersphin…
Jamesgo1 Jan 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions documentation/style-guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,44 @@ Unix
The name of the operating system developed at AT&T Bell Labs in the early
1970s.

Diátaxis
========

Python's documentation follows the `Diátaxis <https://diataxis.fr//>`_
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I forgot to include this in my first review: this should definitely be something like: Python's documentation is moving towards an implementation of Diátaxis. It's not there yet by any means!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe something like "strives to follow", so we don't need to update the text once we do get there?

framework. This means adapting the writing style according to the nature of
the documentation that is being written. The framework splits documentation
into four distinct types: tutorials, how-to guides, reference, and
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd prefer to say: "... identifies documentation of four distinct types: ..." (because although often or usually this means an architectural division too, it's not the most important thing).

explanation.

`Python tutorials <https://docs.python.org/3/tutorial/index.html>`_ should be
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This ought to be a Sphinx reference, I guess using InterSphinx.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And as you mentioned below, it should be tutorial -- singular.

beginner-friendly, explicit, and avoid making assumptions about the reader's
knowledge. The goal of a tutorial is to get the user writing Python code as
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In fact there is a single Python tutorial - this end-to-end learning journey that has been conceived and implemented, and I think that's an important fact about it. I think I would like to say something like:

The goal of the tutorial is to provide a learning experience, in which a user is guided through a series of activities, and in doing so encounters concepts, actions tools and so on. The minimum possible explanation and technical detail should be provided (link to further information when required).

I'd actually say nothing about beginners - there could be in principle a very advanced tutorial.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also possible to link to https://diataxis.fr/tutorials/ - also available via InterSphinx.

quickly as possible with clear logical steps. Explanations and abstract
concepts should be avoided.

`Python how-to guides <https://docs.python.org/3/howto/index.html>`_ are
similar but distinct from tutorials and the two are often conflated. Both
tutorials and how-to guides are instructional rather than explanatory
and should provide clear, logical steps on how to complete a task. However,
how-to guides make more assumptions about the user's knoweldge and place
greater emphasis on the user finding the best way to complete the task.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think good language for how-to guides is around "problems". E.g.: "A how-to guide talks the user through a problem-field." Sometimes it's a simple 1-2-3-4 series of operations, but more often it's more complex than that.

The key thing is that how-to guides are to help someone get their work done.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would also use a more concrete language and focus on what they are first, and how they are similar and/or different from the tutorials afterwards.


`Python references <https://docs.python.org/3/library/index.html>`_ should
be factual, concise, and clear. The purpose of reference documentation is
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we need to say that anything should be concise or clear - that's probably a given for documentation.

to describe rather than explain. Accuracy and consistency are imperative as
this type of documentation should be seen as an authoritative source.
:ref:`Code-examples` can be a useful way of achieving these
objectives.

`Python explanations <https://docs.python.org/3/glossary.htmll>`_ provide
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

explanation singular.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure the glossary is a good example of explanation, and we don't really have a section for those. Some documents (e.g. a good chunk of the Unicode HOWTO) could be classified as explanations, but they are currently hidden throughout the docs.

There's also a typo in the link (if you use intersphinx this suggestion won't be needed):

Suggested change
`Python explanations <https://docs.python.org/3/glossary.htmll>`_ provide
`Python explanations <https://docs.python.org/3/glossary.html>`_ provide

a deeper level of understanding and are naturally more discursive. They aim
to deepen the reader's understanding and answer 'why' questions. They should
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should use double quotes:

Suggested change
to deepen the reader's understanding and answer 'why' questions. They should
to deepen the reader's understanding and answer "why" questions. They should

provide context, make connections between topics, and discuss alternative
opinions.
hugovk marked this conversation as resolved.
Show resolved Hide resolved

Please consult the Diátaxis guide `here <https://diataxis.fr//>`_ for more
detail.
hugovk marked this conversation as resolved.
Show resolved Hide resolved

Affirmative tone
================

Expand Down Expand Up @@ -159,6 +197,8 @@ module (e.g. OS level pipe buffers filling up and stalling child processes),
these can be documented in a "Common Errors" section and cross-referenced
rather than repeated for every affected interface.

.. _code-examples:

Code examples
=============

Expand Down