rethinkdb / rethinkdb/docs

Have a more prominent way of visually differentiating between driver languages in documentation

Open
#783 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
CSS
Stars
118
Forks
161
PR merge metrics
No merged PRs in 30d

Description

Currently, the only way to clearly see the driver language is to 1. read the URL or 2. go up to the page and see the selected language. I think these are both sub-optimal. You can, of course, actually read the code, but it's so similar across language that it might be confusing and trip up beginners (I'm creating this issue after talking to a user that went through this!). I'm also usually interested in seeing the documentation for a particular language, and it should be clear that I'm in the incorrect language documentation in order to switch quickly to the desired one.

Keep in min that google arbitrarily chooses which language to show for a particular method, so you can never really predict what language you're getting when googling something.

Here are some suggestions for possibly visually differentiating which driver you're currently on. Obviously, I have no knowledge of the documentation system and how it works, so I understand that these might be hard to implement. These are only suggestions and can be disregarded if it doesn't end up making much sense.

  1. Add a language logo or name to the background of the code sample. This might be easy to do.

screen shot 2015-06-02 at 6 59 50 pm

(There's probably a much better way of executing this 😄 )

  1. Have a code switcher in all code snippets with all relevant languages. Stripe uses this on some of its documentation.

screen shot 2015-06-02 at 7 05 19 pm

  1. Always clearly show what language you're currently in in part of the page

Stripe documentation:

screen shot 2015-06-02 at 7 02 23 pm

Django does something similar with version numbers, but it's not as clear:

screen shot 2015-06-02 at 7 09 08 pm

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the documentation system and how it selects and renders driver-language pages and code samples. Compare the suggested approaches, then define one consistent visual indicator for the active language. Done means a reader can identify the current driver language and switch or correct it without relying on the URL or reading the code.

Written by the indexing model from the issue text.

Assessment

Domain
design, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.