You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
The text was updated successfully, but these errors were encountered:
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:
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.
The text was updated successfully, but these errors were encountered: