Docs Design Discussion

[budparr]

Okay, I just started fooling around with this, mocking up in my browser. Here are some things I did, which are up for discussion.

Primary goal of these changes is to make the documentation more readable.

1. Created a separation between navigation/header and the content below.
   Frankly, the navy blue might be too stark of a contrast, but a good starting place.

2. Made the background color of the body near-white, or a slight gray. This is just meant to create a balance of contrast, because on some screens the white becomes very bright.

3. Put the contextual/page TOC in a box with shadow to clearly separate it from the content it serves. (I felt it blended in too much and created an environment where all one saw was a sea of text).

4. Created a max width for body copy and centered it so it has white space on each side. (it's a basic tenet of setting body copy that it's kept at a reasonable width for reading).

5. Left justified the tags. Keeping it simple here. They distract the eye to the right out of proportion to their place on the page.

6. Added space above headings to better separate one section from another (this isn't apparent from the screenshot).

At any rate, it's just a start to get a discussion going on this.

[rdwatters]

I don't know if I mentioned this in the other thread, but this looks great!

What do you think about this?

#27

[digitalcraftsman]

Created a separation between navigation/header and the content below.
Frankly, the navy blue might be too stark of a contrast, but a good starting place.

they should definitely be seperated visually

You added a shadow to the TOC on the right. The shadow let's make the TOC look more important that the actual content.

@budparr what do you think about experimenting with a different color pallet?

[budparr]

@digitalcraftsman Keep in mind that the above was just done with inspect in the browser, just to start thinking.

what do you think about experimenting with a different color pallet?

I think in this context the navy blue I used on the home page becomes overwhelming (I mentioned that above). So, yeah. We need to create that separation, but this may not be it. On the homepage, I think the dark color does a nice job of absorbing the extreme "colorfullness" of the logo.

You added a shadow to the TOC on the right. The shadow let's make the TOC look more important that the actual content.

Point taken.

[rdwatters]

@budparr @digitalcraftsman @bep

I'm good with whatever design decisions you make on this 😄

[bep]

I think it looks really really good, but it would be interesting to see the serif in use in body text in the doc pages as well. It may look odd or ... fantastic.

[rdwatters]

@budparr what are your thoughts on the admonitions?

[budparr]

what are your thoughts on the admonitions?

I think the only thing I didn't address was the potential for using a serif typeface for body copy, which is just something to try and haven't gotten there yet.

[rdwatters]

I think the only thing I didn't address was the potential for using a serif typeface for body copy, which is just something to try and haven't gotten there yet.

@budparr Are you talking about the warn and note admonitions? Not my admonitions from last night. Sorry again, brother 😉

[budparr]

I think you're saying that those are shortcodes and we need to account for them in the design. If so, noted. Thank you.

[rdwatters]

I think you're saying that those are shortcodes and we need to account for them in the design.

Yes, and perhaps for blockquotes as well. I want to eliminate the non-semantic use of <blockquote> for what are really CTAs, admonitions, etc.

The link for the admonitions above takes you to the contrib page with the examples. There is an optional title named parameter for each of the admonitions as well, although I'm not currently displaying them. It might make sense to add a third admonition for tip since this is a common use case. Thoughts?

[budparr]

I've started to build a set of classes for shortcodes, partials (where they are component-like), and internal templates, where appropriate. So whatever is there, they will be designed for.

[rdwatters]

@budparr Couple Qs:

• With the new design you're working on, are you going to respect the same classes for the site navigation? See Improve build performance of docs site [HELP NEEDED] #44 for some context.

I've started to build a set of classes for shortcodes, partials (where they are component-like), and internal templates

• Anything I should know w/r/t images/figures/video? I ask because I will be adding new content files today that will include screenshots and similar content, and it makes sense for me to use these now if this is what you're planning. As an aside, I built a pretty solid youtube shortcode {{yt}} that pulls in a thumbnail and then only injects the iframe after user interaction (big perf boost on slow mobile). It's in a private work repo, and I need to check the JS, but let me know if you think it has some utility for something like the blog. (My guess is the docs will have very few videos, at least for now). Thanks!

[budparr]

That youtube shortcode sounds great (I've got another project I can use it on!). I'll make sure that I respect any necessary classes.

[rdwatters]

Called as such:

{{< yt id="123456" thumbnail="my-vid-thumb.jpg" description="My vid description" >}}

thumbnail and description are optional.

Example on temp page:

https://hugodocs.info/test

SCSS:
https://github.com/rdwatters/hugo-docs-concept/blob/master/pipeline/scss/components/_video.scss

Shortcode:
https://github.com/rdwatters/hugo-docs-concept/blob/master/layouts/shortcodes/yt.html

JS:
https://github.com/rdwatters/hugo-docs-concept/blob/master/pipeline/js/scripts/video-thumbnail-switch.js

NOTE You'll see a vimeo reference in the JS, which won't make a difference now. I had it working before, but perhaps vimeo changed their API. I'll need to look into this...in a few weeks. Cheers.

[rdwatters]

@budparr

In the interest of time (and of course we can change this as much as needed, I've at least lined up the colors per your suggested in-browser edits:

https://hugodocs.info/about/

[rdwatters]

@budparr Seems like your respective repositories are better places to have these discussions. Therefore, closing...