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 · 5 comments
Open

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

opriz opened this issue Nov 26, 2021 · 5 comments
Labels
FeatureRequest NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. website
Milestone

Comments

@opriz
Copy link

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
Member

seankhliao commented Nov 26, 2021

cc @dmitshur

@mknyszek mknyszek added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Nov 30, 2021
@rsc
Copy link
Contributor

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 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 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.

@MarkMoretto
Copy link

MarkMoretto commented Jul 3, 2022

If this is still in the works, I'd add in syntax highlighting beyond just a shade change would be nice. Possibly a light and dark version.

For someone just learning the language, which is already a bit complex compared to something like JavaScript or Python, distinguishing keywords from values and anything else that might be relevant could be helpful.

Rust has a great set of websites that allow for toggling of a handful of palettes, which helps to distinguish documentation from snippets and examples. I think the platform powering those documents is mdBook.

Just my $.02. I know y'all are doing this in your spare time and all of us Gophers definitely appreciate it!

(If I can help at all, please let me know.)

Thanks for reading!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
FeatureRequest NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. website
Projects
None yet
Development

No branches or pull requests

8 participants