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.

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

Choose a programming language from the navbar once, rather than for each code box. #133

Open
sir-kokabi opened this issue May 16, 2024 · 0 comments

Comments

@sir-kokabi
Copy link

We have two types of documentation formats:

  1. Docs where the programming language must be selected for each individual code box.
    image

  2. Docs where the programming language is chosen once from the navigation bar, applying the selection to all code snippets throughout the documentation.
    image

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant