Adopting the Diátaxis framework for Python documentation

Documentation
32

I don’t recall any active pushback in any of the various threads, although I can’t find a record of this having been posted to python-dev. There have been cautions though of ensuring that there isn’t too much churn, and that each docs page is still complete enough to find things (Ezio’s point above). These though seem more to do with how we approach the project and change management, rather than the philisophical point of Diátaxis as an approach.

A

1 Like
33

The yellow box is at the bottom of the page, including on the 3.9 version. That’s because it’s assumed that people usually arrive at the HOWTO from a reference page.

1 Like
34

I for one am +1. I’m familiar with the Diátaxis framework from work.

4 Likes
35

+1, IMO we do have general consensus.

2 Likes
36

It’s hard to argue against Diataxis as a north star, and I am fine with it. (In fact I like the distinctions it makes quite a bit.) But it seems whenever it comes up we end up having to explain that Diataxis itself advises against well-meaning but overly ambitious restructuring plan – such plans will cause a lot of unnecessary alarm amongst people who fear churn (myself among them).

So I’m not sure what we can do specifically now that we’re accepting Diataxis. I feel we need something concrete to strive for, but it should discourage churn. I’m not sure what that plan would be.

4 Likes
37

I think a good first step would be to survey what we already have:

  • What “patterns” are we using? Different documents use different “patterns”, such as:
  • Which of these “patterns” are closer to the Diataxis model? Which ones seem to work best? Can we recommend a specific pattern to follow consistently?
  • What documents can benefit from an update (or an overhaul)? What are the longest documents? Can we reorganize/split them following the Diataxis model?
  • Are there already open issues on the tracker about reorganizing certain docs? Which documents/modules have the most issues?
  • Are there other metrics that might give us some useful insights (e.g. number of page hits or StackOverflow questions)? Which documents should we prioritize?
  • Do the translation teams have any feedback about which documents can be improved, since they are going through all of them already?

The answers to these questions will help us identify some documents that can be improved/reorganized/split, establish some guidelines, priorities, and update paths that we can follow to make our docs more consistent and easier to navigate.

That said, I’ve been also thinking how examples fits in the Diataxis model, since I find them quite valuable and I think we should add more.

A good portion of our documentation falls into the “reference” quadrant, and About reference - Diátaxis seems to suggest that examples should be included there – at least when they focus on individual APIs. However we also have more complex examples that might fit better into an how-to section (or page).

Should we strive to add an “Examples” section to each module? Should examples about individual APIs be kept inline or grouped in this section, in order to make the reference more compact and easier to navigate?

I guess the answer might change depending on the individual documents, but I’m curious to hear if you have any feedback about this.

38

Well, here is the point of view of a documentation translator. Most stdlib modules are documented with just a reference-style document, which of course is necessary. I think HOWTOs / understanding become needed if the module is particularly large or complex, or contains language concepts (e.g. async I/O or abstract base classes). On the other hand, I would say many if not most would benefit from a tutorial-like intro. As an example, take the ast module docs, which I translated:

https://docs.python.org/3/library/ast.html

I think this is a perfect example of a page that should be restructured.

  • After two paragraphs of introduction with technical terms, it starts right away with a copy of the full Python grammar, which is hairy from the beginner point of view,
  • Then it gives a detailed description of every single AST node,
  • And only then, you find the information that you would have needed to start your journey with the module, namely the functions to parse an AST and manipulate it.

I would do it this way instead:

  • An “AST overview” section demonstrating usage of parse() and attribute access on AST nodes with examples at the REPL (perhaps also showing how pattern matching can be used elegantly on ASTs),
  • Then the descriptions of the individual nodes,
  • Finally, as an appendix, the Python grammar.

The first part roughly corresponds to a tutorial, the rest is reference. Again, for many modules, I don’t see a need for more, but from experience of walking through stdlib modules that I have no prior knowledge of to translate them, I do miss more tutorials.

Another example of a module that would benefit from a tutorial is the re module. There are already quite good docs:

https://docs.python.org/3/howto/regex.html

On the other hand, even on the HOWTO, you get to read some text that is a little heavy reading (at least for a primer on regexes) on metacharacters and stuff before learning how to execute a regular expression on a string. Here it might be beneficial to add a small tutorial with simple steps to get started with regexes.

An example that I consider good is the argparse docs. There are

  • a tutorial (actually in the HOWTO section):

https://docs.python.org/3/howto/argparse.html

  • the reference:

https://docs.python.org/3/library/argparse.html

With the tutorial, you quickly get a basic grasp of how using argparse feels like, and it gradually introduces more advanced concepts. Perhaps some of the material from the reference could be split into a HOWTO (e.g., how to use subparsers).

So, bottom line: in my opinion, the stdlib docs need more beginner-level material to help people get a basic grasp of stdlib modules before going into the fussy details.

9 Likes
39

A user perspective: I use the Python documentation very often, and prefer it over other sources.

  • csv module

    • I use this module sometimes, but not that often.
      I always have to look up the examples, because the API is not that easy to remember.
    • The examples are a bit inconveniently placed, some in the middle of the page, some at the end.
      → The “simplest reading example” and the “simplest writing example” should be duplicated at the very top.
    • The exotic example quotechar examples could be moved to the end.
    • The fmtparams is never actually explained explicitly. Basically it seems one has to guess based on the examples. Adding an explanation and explicitly enumerated parameters would be great.
    • The simple DictReader and DictWriter examples should also be duplicated at the very top, and in the examples section.
    • The sidebar would be more helpful if the most important functions (reader, writer) and classes (DictReader, DictWriter) were listed explicitly.

  • json module

    • I use this module very often.
      I rarely have to look up anything, because the API is easy to remember.
      The examples are conveniently placed at the top.
    • Maybe the simple loads examples could be moved up a bit more even, to the very top.

  • logging module

    • I use this module regularly, but only the basics.
    • There are zero examples. That seems inconvenient.
    • The “simple example” from the basic tutorial page should be duplicated to the very top on the main page.

  • socket module

    • I remember using this module only infrequently.
    • The documentation jumps directly into very technical low-level details without any examples or explanations. That seems quite daunting.
    • It would benefit from a lot of inline examples.

  • re module

    • I use this module very often.
      I have to look up certain details all the time.
      The documentation is quite nice, with inline examples.
    • The main thing missing is an overview index with links to the different syntax elements, and to the most common functions (match, search, findall, compile, split, sub).
12 Likes
40

Excellent feedback!

41

This may be only tangentially related to the quality of Diátaxis, but trying to print the front page of their website (https://diataxis.fr/) for reference, almost kills my Chrome instance, which tries to produce 34,240 pages. I hope printing a single page of Python documentation in Diátaxis will not pull tens of thousands of pages.

42

That’s due to a Chrome bug. See details in Printing on Chrome generates way too many pages · Issue #358 · pradyunsg/furo · GitHub.

I’m guessing the Diataxis documentation is built with an old version of Furo as its base or makes changes in its stylesheet that reintroduces the issue. Firefox should work just fine. :slight_smile:

1 Like
43

I have thought about this before. One problem is that not infrequently, an example would break the flow because you have to explain things in sufficient detail to have the example make sense. It might not break the flow for you the very first time you need the example, but then you have to scroll past it every single time thereafter.

It would improve this aspect of the documentation to be able to make use of the HTML5 summary-detail elements, but to do this properly would need support at the Sphinx and perhaps docutils levels. As far as I know, that support isn’t available, though you can simulate it in a theme as I’ve done here. With such support, examples would take up just one line by default when in an unexpanded state, and as much space as needed when actually expanded by someone who needs to refer to the example. Another approach would be to use HTML tooltips to show examples while hovering over an “example” icon or similar, but again that would need choosing a suitable browser-side tooltip framework, play nicely with third-party themes and other build targets (than HTML), etc.

1 Like
44

There’s a simpler workaround: see my answer on StackOverflow Sphinx, reStructuredText show/hide code snippets - Stack Overflow

45

From a docutils / Sphinx perspective we could add support[1], although it would be hard to fit into the conceptual model of an “abstract document”, as e.g. PDF, ePub, OpenDocument don’t have similar support to the best of my knowedge. I also don’t believe there’s precedent for a writer-specific directive.

A

  1. For example a .. collapsible:: directive that only takes effect on HTML writers/builders, and is a no-op on others. ↩︎

46

Well, a number of those answers would work, as does the approach in my theme. But IMO these approaches are a bit too error-prone for widespread use.

Agreed, but it seems the cleanest way to provide a definite quality improvment for what is probably the largest community of documentation readers. Rather than being a no-op on non-HTML platforms, it could be configured while building to either show nothing or the full expanded content.

47

The unittest docs include a basic example near the top, that explains the basic concepts in some details. At the very top of the page I added a shortcut that links to the assert methods, for people that are already familiar with the basic concept and just want to skip ahead to the reference. (Aside: the unittest docs might be a good candidate for a overhaul, and there have been several discussions about it in the past).

Note that depending on the the theme used, collapsed examples might be fairly easy to miss, especially while skimming through.

Anecdotally, I recently posted a short message on GitHub with two collapsed sections, and when I referred to them I had two people asking me what message I was talking about because they both didn’t notice/realize that in that message there were two collapsed sections. On GitHub (and by default in HTML5) the only hint is a small ⯈.

This doesn’t sound very usable if you want to select/copy/scroll, even though it might depend on the exact implementation of the tooltip.

1 Like
48

Yes, and I believe there are implementations where you can do all of scroll/select/copy.

49

Hiding examples in tooltips sounds undesirable to me, and I’d hope there would be a plain version without that.

1 Like
50

(@moderators, please could this thread be split from Adopting the Diátaxis framework for Python documentation - #43 by vsajip as the first post in the <details> conversation?)

A PR for Sphinx is up a Add support for collapsible content by AA-Turner · Pull Request #10532 · sphinx-doc/sphinx · GitHub – I’d appreciate if you could add a little detail on how you’d like the option to work in a comment on the PR, as I wasn’t too sure.

A

2 Likes
51

Well, this doesn’t need to be done in docutils or Sphinx natively – there’s a Sphinx extension written by one of the Sphinx maintainers for this:

4 Likes