evildmp
Choose a programming language from the navbar once, rather than for each code box.
We have two types of documentation formats:
-
Docs where the programming language must be selected for each individual code box.
-
Docs where the programming language is chosen once from the navigation bar, applying the selection to all code snippets throughout the documentation.
The second format offers several advantages:
- Enhanced efficiency for readers, as they don't need to choose a language for every code box.
- Streamlined and aesthetically pleasing design.
Selecting a programming language once and having it applied to all examples in the documentation aligns with user expectations, similar to choosing a website's language once and having it remain consistent throughout. Just like we don't expect to switch the text language paragraph by paragraph and only switch the site's language once, we wanna choose a programming language once and see all examples in that language throughout the docs.
I believe the second format could become a standard in diataxis framework, though further discussion and analysis would be beneficial.
One might wonder why this more user-friendly format isn't more widely adopted, even by major companies. It is possible that they may have specific reasons for retaining the first format; however, I believe that the second format has broader potential and should be more widely implemented.
- Docs where the programming language must be selected for each individual code box.
There are tools that will store this selection and apply it to all code blocks. For instance, mkdocs-material has a "Linked content tabs" feature that will synchronize tabs. The displayed example shows it working for code blocks specifically as well.
If you were implementing a documentation generator / framework on your own, this could be implemented by storing the preference in as a JS variable once clicked and rendering all code blocks based on the preference variable. You could also persist this between page loads by storing the preference in localStorage or similar
I believe storing the selection as such is quite intuitive and does not require any additional buttons.
- Docs where the programming language is chosen once from the navigation bar, applying the selection to all code snippets throughout the documentation.
The example screenshot you provided is of Playwright, where the language selection affects quite a bit more than just code snippets. It changes the installation, integration (as a pytest plugin with its own API for Python specifically as in your screenshot), codegen, the API reference (including conventions like snake_case for Python vs camelCase for JS, etc), etc.
So I think Playwright specifically has multiple reasons to provide a top-level selection because it affects a decent amount more than code snippets in its case. As this type of decision may vary based on the content of the documentation, it may be out-of-scope for Diataxis. In Playwright's case, the language selection could be considered a hierarchical parent of the entire Diataxis organization scheme, i.e. each language could individually follow Diataxis internally.
With all due respect, I find your reasoning unconvincing.
As someone who writes code, I believe that choosing a tool or language for every individual code block is both unnecessary and frustrating. Most developers tend to stick to specific tools and languages for their projects, so having to select a tool for each code block feels repetitive and redundant.
While this approach might be helpful in a few rare cases or for some individuals, it is generally unnecessary. When creating frameworks, we should prioritize the needs of the majority, not cater to outlier situations.
This isn't to suggest that the option to choose a tool for each code block should be removed. Rather, it could be presented as an optional feature that allows users to change the default tool choice if they prefer.
In fact, I believe this principle could be applied to other parts of documentation as well. For example, when reading documentation, it would be helpful if the system recognized key details like my operating system, IDE, and other relevant tools. This way, the documentation could provide customized information specific to my setup, eliminating the need to sift through irrelevant steps for other environments.
I think you misunderstood my comment. I agree that repetitively choosing a language is unnecessary and can be a poor UX.
But that doesn't mean the language choice needs to be in the navbar. It can be kept in-line in the code block and the documentation site can remember your choice across all code blocks. As I wrote above, mkdocs-material's "Linked content tabs" feature does exactly this.
I appreciate your response. However, my suggestion goes beyond just remembering the selection within code snippets—I believe a global selection (e.g., via the navbar) is a best practice that should be encouraged more broadly, and I propose considering it as a recommendation in the Diataxis documentation framework.
My reasoning is that developers typically work within a consistent environment—whether that means using a specific programming language, operating system, or toolset. If documentation frameworks allow users to set their environment once (language, OS, etc.), they can receive personalized, streamlined documentation without having to filter out irrelevant information manually. For instance:
- A user selects Windows as their OS → They only see Windows-specific installation steps.
- A user selects Python as their language → All examples are automatically shown in Python.
This principle is already implemented effectively in some documentation (e.g., Playwright), where the language selection affects installation, integration, API references, and conventions. I believe this approach could be extended further across more frameworks.
Regarding mkdocs-material, I acknowledge that it has a "Linked content tabs" feature, which syncs the selected language across code blocks. However, do other documentation generators and static site generators offer this? If not, a best practice recommendation within Diataxis could encourage broader adoption across different tools.
Ultimately, my suggestion is not to remove per-code-block selection but to add a higher-level, global option that enhances efficiency and improves the overall user experience.
Would love to hear your thoughts on this!