gh-1145: Add an overview of Diátaxis to the style guide #1177
Conversation
|
cc. @evildmp |
documentation/style-guide.rst
Outdated
| Python's documentation follows the `Diátaxis <https://diataxis.fr//>`_ | ||
| 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 |
There was a problem hiding this comment.
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).
documentation/style-guide.rst
Outdated
| into four distinct types: tutorials, how-to guides, reference, and | ||
| explanation. | ||
|
|
||
| `Python tutorials <https://docs.python.org/3/tutorial/index.html>`_ should be |
There was a problem hiding this comment.
This ought to be a Sphinx reference, I guess using InterSphinx.
There was a problem hiding this comment.
And as you mentioned below, it should be tutorial -- singular.
documentation/style-guide.rst
Outdated
|
|
||
| `Python tutorials <https://docs.python.org/3/tutorial/index.html>`_ should be | ||
| 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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Also possible to link to https://diataxis.fr/tutorials/ - also available via InterSphinx.
documentation/style-guide.rst
Outdated
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
documentation/style-guide.rst
Outdated
| greater emphasis on the user finding the best way to complete the task. | ||
|
|
||
| `Python references <https://docs.python.org/3/library/index.html>`_ should | ||
| be factual, concise, and clear. The purpose of reference documentation is |
There was a problem hiding this comment.
I don't think we need to say that anything should be concise or clear - that's probably a given for documentation.
documentation/style-guide.rst
Outdated
| :ref:`Code-examples` can be a useful way of achieving these | ||
| objectives. | ||
|
|
||
| `Python explanations <https://docs.python.org/3/glossary.htmll>`_ provide |
documentation/style-guide.rst
Outdated
| Diátaxis | ||
| ======== | ||
|
|
||
| Python's documentation follows the `Diátaxis <https://diataxis.fr//>`_ |
There was a problem hiding this comment.
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!
There was a problem hiding this comment.
Maybe something like "strives to follow", so we don't need to update the text once we do get there?
AA-Turner
changed the title
documentation/style-guide.rst
Outdated
| Diátaxis | ||
| ======== | ||
|
|
||
| Python's documentation follows the `Diátaxis <https://diataxis.fr//>`_ |
There was a problem hiding this comment.
Maybe something like "strives to follow", so we don't need to update the text once we do get there?
documentation/style-guide.rst
Outdated
| into four distinct types: tutorials, how-to guides, reference, and | ||
| explanation. | ||
|
|
||
| `Python tutorials <https://docs.python.org/3/tutorial/index.html>`_ should be |
There was a problem hiding this comment.
And as you mentioned below, it should be tutorial -- singular.
documentation/style-guide.rst
Outdated
| 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. |
There was a problem hiding this comment.
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.
documentation/style-guide.rst
Outdated
| :ref:`Code-examples` can be a useful way of achieving these | ||
| objectives. | ||
|
|
||
| `Python explanations <https://docs.python.org/3/glossary.htmll>`_ provide |
There was a problem hiding this comment.
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):
| `Python explanations <https://docs.python.org/3/glossary.htmll>`_ provide | |
| `Python explanations <https://docs.python.org/3/glossary.html>`_ provide |
documentation/style-guide.rst
Outdated
|
|
||
| `Python explanations <https://docs.python.org/3/glossary.htmll>`_ 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 |
There was a problem hiding this comment.
I think this should use double quotes:
| to deepen the reader's understanding and answer 'why' questions. They should | |
| to deepen the reader's understanding and answer "why" questions. They should |
|
@Jamesgo1 Thanks for submitting your first PR to the devguide. If you can fix these few review suggestions, we can rereview and merge since this is a helpful addition. 🌻 |
willingc
added
the
needs: PR update
|
Thanks so much for the feedback! Just messaging to say I'm still working on this but I've just been really busy these last couple of weeks. I should hopefully have more time now. |
|
Thanks for checking in @Jamesgo1. No stress. We all have things going on. Very grateful that you are working on this and it is off to a great start. |
|
Sorry for the delay on this! Thanks a lot for your feedback @ezio-melotti and @evildmp. All your suggestions make sense and I've tried to implement them as best as I can. I've changed the references to inter-sphinx (thanks for your help @AA-Turner). The how-to index doesn't seem to have a reference in the cpython docs so that's the only one I didn't change. I've tried to make the wording more concise/less verbose based on your feedback @ezio-melotti Of course, happy to refine again based on any other feedback. |
willingc
removed
the
needs: PR update
…x link for tutorials.
Hello,
I've made an initial attempt at adding a Diataxis section to the style guide based on the issue here. Any feedback appreciated.
📚 Documentation preview 📚: https://cpython-devguide--1177.org.readthedocs.build/