Applying Diátaxis concepts to our docs

[dangotbanned]

What is your suggestion?

Adapted from (#3500 (comment))

What is Diátaxis

A systematic approach to technical documentation authoring.

Diátaxis is a way of thinking about and doing documentation.
It prescribes approaches to content, architecture and form that emerge from a systematic approach to understanding the needs of documentation users.

Related discussions

• https://discuss.python.org/t/diataxis-and-python-documentation/41836
• Conceptual guide: Best practices for data visualization using Altair #3117

Background

@joelostblom

ideal place to have example code. So far we have mostly included it in the User Guide and Gallery, but not really in the docstrings.
Having said that, I think it is helpful to see at least some simple examples directly in the docstring, but also that we are consistent so that users know where they can find the example code.

@dangotbanned

I've seen diataxis mentioned in altair before (#3117), which might be helpful in achieving consistency

@joelostblom (#3500 (comment))

A third approach would be something in between with just a simple example in the docstring and more elaboration in the User Guide.
Pros: There is both something directly in the docstring and also an elaborate version in the User Guide.
Cons: We're now updating in two places, but maybe the docstring example can be keep so simple that it doesn't matter much.

Of the options presented, this would be my preference with ...

Proposal (@dangotbanned)

I'm viewing examples less in terms of simple vs complex, and more in terms of serving the context they are displayed in.
Of course these may overlap to some degree, but I think the needs differ enough to naturally lead to different examples written:

Docstrings/API Reference

• Showing you how the object/function is used
• Focused on utility, minimal discussion

Examples

when()

altair/altair/vegalite/v5/api.py

Lines 1275 to 1320 in 23b1891

	Examples
	--------
	Setting up a common chart::
	import altair as alt
	from vega_datasets import data
	source = data.cars()
	brush = alt.selection_interval()
	points = (
	alt.Chart(source)
	.mark_point()
	.encode(x="Horsepower", y="Miles_per_Gallon")
	.add_params(brush)
	)
	points
	Basic ``if-then-else`` conditions translate directly to ``when-then-otherwise``::
	points.encode(color=alt.when(brush).then("Origin").otherwise(alt.value("lightgray")))
	Omitting the ``.otherwise()`` clause will use the channel default instead::
	points.encode(color=alt.when(brush).then("Origin"))
	Predicates passed as positional arguments will be reduced with ``&``::
	points.encode(
	color=alt.when(
	brush, (alt.datum.Miles_per_Gallon >= 30) | (alt.datum.Horsepower >= 130)
	)
	.then("Origin")
	.otherwise(alt.value("lightgray"))
	)
	Using keyword-argument ``constraints`` can simplify compositions like::
	verbose_composition = (
	(alt.datum.Name == "Name_1")
	& (alt.datum.Color == "Green")
	& (alt.datum.Age == 25)
	& (alt.datum.StartDate == "2000-10-01")
	)
	when_verbose = alt.when(verbose_composition)
	when_concise = alt.when(Name="Name_1", Color="Green", Age=25, StartDate="2000-10-01")
	"""

Chart.transform_filter()

altair/altair/vegalite/v5/api.py

Lines 3042 to 3088 in 23b1891

	Examples
	--------
	Setting up a common chart::
	import altair as alt
	from altair import datum
	from vega_datasets import data
	source = data.population.url
	chart = (
	alt.Chart(source)
	.mark_line()
	.encode(
	x="age:O",
	y="sum(people):Q",
	color=alt.Color("year:O").legend(symbolType="square"),
	)
	)
	chart
	Singular predicates can be expressed via ``datum``::
	chart.transform_filter(datum.year <= 1980)
	We can also use selection parameters directly::
	selection = alt.selection_point(encodings=["color"], bind="legend")
	chart.transform_filter(selection).add_params(selection)
	Or a field predicate::
	between_1950_60 = alt.FieldRangePredicate(field="year", range=[1950, 1960])
	chart.transform_filter(between_1950_60) | chart.transform_filter(~between_1950_60)
	Predicates can be composed together using logical operands::
	chart.transform_filter(between_1950_60 | (datum.year == 1850))
	Predicates passed as positional arguments will be reduced with ``&``::
	chart.transform_filter(datum.year > 1980, datum.age != 90)
	Using keyword-argument ``constraints`` can simplify compositions like::
	verbose_composition = chart.transform_filter((datum.year == 2000) & (datum.sex == 1))
	chart.transform_filter(year=2000, sex=1)
	"""

User Guide

• Showing you how the altair API fits together
• Higher level, discussing why you'd reach for certain tools
• Doesn't go through every possible permutation

Gallery

• Showing how to produce specific charts
• Currently these are mostly short description, some have inline comments
• Goal-oriented

How this fits into our docs (@joelostblom)

Adapted from (#3500 (comment))

@dangotbanned

I've seen diataxis mentioned in altair before (#3117), which might be helpful in achieving consistency

Good reminder! I also think this could be helpful in the larger picture, but it's a bigger project for me to understand diataxis more intimately and think about if it would serve us to (iteratively) move towards that.
But I had a glance at the page and as per https://diataxis.fr/compass/ and https://diataxis.fr/complex-hierarchies/ maybe our current docs map onto diataxis something like this (mostly for future reference):

Diataxis	Altair
Tutorial	User guide
How to guide	Getting started + Gallery
Reference	API reference
Explanation	Advanced usage + a little bit here and there

I also think it would be helpful with something simple like more (two-way) links between the User Guide and the Gallery examples to guide readers toward more relevant information.

@dangotbanned

So I definitely appreciate examples in docstrings, but would be hesitant in adding them to autogenerated docstrings. They are already very long and repetitive, adding examples into the mix I think would be overwhelming.

I agree with this.

@dangotbanned

...and more in terms of serving the context they are displayed in.

I find this framing and the structure in your proposal helpful. Let's proceed with that framework as our guide for deciding where to put examples and what they should look like.

What next?

I'm hoping this issue can serve as a place for discussion and act as a parent issue for smaller (more manageable) sub-tasks - if we can agree some areas of focus.
Any outcomes of the process itself can also help inform guides we provide to potential contributors.

Rejected Ideas

Examples in autogenerated docstrings

@joelostblom

would have to add examples to a fair amount of objects (can we even do it for what we autogenerate from Vega-Lite such as the marks, transform, etc?), would we have the same

@dangotbanned

So I definitely appreciate examples in docstrings, but would be hesitant in adding them to autogenerated docstrings.
They are already very long and repetitive, adding examples into the mix I think would be overwhelming.

Also if they are not written by hand, I expect they will be of low utility:

• E.g. just demonstrating which values are allowed
• Rather than showing examples of why you might pass specific arguments