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

x/website: set background color for tutorial code snippets #49803

Open
opriz opened this issue Nov 26, 2021 · 4 comments
Open

x/website: set background color for tutorial code snippets #49803

opriz opened this issue Nov 26, 2021 · 4 comments

Comments

@opriz
Copy link

@opriz opriz commented Nov 26, 2021

What is the URL of the page with the issue?

https://go.dev/doc/tutorial/getting-started

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.20 Safari/537.36

Screenshot

image

What did you do?

nothing

What did you expect to see?

I would suggest the website use gray background for commands and codes, like markdown style.

What did you see instead?

commands and codes are similar to other content

@gopherbot gopherbot added this to the Unreleased milestone Nov 26, 2021
@seankhliao seankhliao changed the title x/website: x/website: set background color for tour code snippets Nov 26, 2021
@seankhliao seankhliao changed the title x/website: set background color for tour code snippets x/website: set background color for tutorial code snippets Nov 26, 2021
@seankhliao
Copy link
Contributor

@seankhliao seankhliao commented Nov 26, 2021

@rsc
Copy link
Contributor

@rsc rsc commented Nov 30, 2021

Generally speaking, this is by design, not a bug. What GitHub does where every piece of code font text has its own box and background is typographically clumsy, as demonstrated by this sentence.

Is the tutorial somehow not readable? It seems perfectly fine to me. Many many books have been written with code displays that don't have backgrounds. See for example The Go Programming Language.

@cespare
Copy link
Contributor

@cespare cespare commented Nov 30, 2021

I think readability is improved by a subtle background color difference, even if it looks aesthetically unpleasant to some.

The reason is that some semantics are being conveyed by the choice to write some text in code font, but it is easy to miss the difference when only the typeface is different. Here's an example from the text above:

  • Declare a main package (a package is a way to group functions, and it's made up of all the files in the same directory).

Without the background color difference, and depending on what fonts are actually used (system-dependent), it may be easy to miss that main is a different font, and read it like this:

  • Declare a main package (a package is a way to group functions, and it's made up of all the files in the same directory).

That changes the meaning. The reader being introduced to Go would think that this is talking about some abstract "main package", not realizing that it is actually a specific package name main.

It's a minor thing, but I believe the downsides of the change are even less significant.

@opriz
Copy link
Author

@opriz opriz commented Dec 1, 2021

I believe the tutorial has few confusing point but it could be better. Many websites may have reasons to support the Markdown style.

Furthermore, the website is inconsistent in style, we can see the grey background for code in blog articles (like json-rpc) or package documentations (like bufio). It seems authors prefer to choose what they like and there is no rule.

Anyway, I think it might be meticulous and trivial work to unify the style, and it does involve the input-output ratio.

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

Successfully merging a pull request may close this issue.

None yet
6 participants