Proposal for a fresh look and better information hierarchy

[pastelsky]

I'm happy to see webpack.js.org shaping up, although it could certainly be better in terms of design / ux and the way information is presented to the user. While I know that the current priority is on finishing up existing documentation, here are a few deficiencies I noticed -

1. The tone and use of grammar isn't consistent across pages and there are quite a few grammatical / spelling errors.
2. The design and information heirarchy, although better than the previous site, is still behind most project documentation sites I've seen.
3. The call to actions aren't clear.

Here are a few sketches I whipped up in my free time, that if the team likes, can be used for the new site. I'd be happy to get some feedback and help with writing css styles for the site.

Homepage

• Clear call to action (Getting started)
• A picture is worth a thousand words — a new svg version of module bundling image which can be even be animated.
• Symmetrical & attractive

Getting started

• Crisp introduction to webpack (current documentation gives a long history of task runners / module bundlers which users may already be familiar with)
• Quickly move to installation and a simple but practical configuration (the current documentation shows a "warning alert box" even before a user has started)
• One can break the page into multiple steps (each on a new page) to prevent information overload.

Documentation Pages

(below is a sample of the configuration page)

• Better grouping of properties (eg. resolve and resolveLoader are two different options)
• Sorting of configuration options by frequency of use / importance rather than using alphabetical order.

Color & Typography

• Consistent use of color / removing too many scattered color shades that dilute identity
• Better readability of body font for long paragraphs — more whitespace and a different font
• Color scheme for syntax highlighting which is soothing to eyes / in-line with rest of the color scheme.
• Better text contrast - enhanced accessibility.

[bebraw]

The tone and use of grammar isn't consistent across pages and there are quite a few grammatical / spelling errors.

We are operating with a very limited resources here (lots of authors, zero budget). That's why we provided the "edit" button so people can fix if they spot something obvious.

The design and information heirarchy, although better than the previous site, is still behind most project documentation sites I've seen.

Can you provide a better design?

Crisp introduction to webpack (current documentation gives a long history of task runners / module bundlers which users may already be familiar with)

The assumption is that the user doesn't understand the difference yet. I'm going with the lowest common denominator here. I have written an expanded article on the topic elsewhere so I tried to keep that as minimal as possible.

Quickly move to installation and a simple but practical configuration (the current documentation shows a "warning alert box" even before a user has started)

I've seen people struggle trying to run webpack on 0.10 or old version like that. I would rather avoid that.

One can break the page into multiple steps (each on a new page) to prevent information overload.

PR welcome. Thanks. 👍

[pastelsky]

We are operating with a very limited resources here (lots of authors, zero budget). That's why we provided the "edit" button so people can fix if they spot something obvious.

I'll see how I can help proofread it in my free travel time.

Can you provide a better design?

Well, I've tried to do so in the sketches.

I've seen people struggle trying to run webpack on 0.10 or old version like that. I would rather avoid that.

Maybe a "prerequisites" section would be a less overwhelming option than the yellow warning box.

PR welcome. Thanks.

I'd love to send out PR's for improving the design /information structure, but before that, I wanted to know if the webpack team is open to this change and how this plays along with the release for 2.0

[bebraw]

I'll see how I can help proofread it in my free travel time.

Ok, great. 👍

Well, I've tried to do so in the sketches.

The sketches are cool. I was more worried about the information architecture (high level layout).

I'd love to send out PR's for improving the design /information structure, but before that, I wanted to know if the webpack team is open to this change and how this plays along with the release for 2.0

I did the prerequisite change (section of its own now). That will get deployed after some design work has been merged (mainly search).

I think @skipjack will comment better on the design related issues.

[pastelsky]

I was more worried about the information architecture (high level layout).

A good design can help supplement that to a certain extent. For. eg. If you compare the current side navigation on the configuration page with the one in the sketch.

[bebraw]

A good design can help supplement that to a certain extent. For. eg. If you compare the current side navigation on the configuration page with the one in the sketch.

The hierarchy looks nice, yeah. 👍 for that.

[skipjack]

I'm not sure an entire redesign is necessary at this point, however I do agree that there are some pieces that need work:

1. The (non-mobile) side navigation definitely needs work. It's not strong visually yet and could probably use a little functionality cleanup as well. I like your design for it. You'd be more than welcome to open a PR for this, I probably should have already created an issue for it as I knew it was a problem.
2. The dark color scheme for top section of the landing page does look nice and we should probably display it at 100vh for most screen sizes. It seems you're proposing blowing away or moving the all sections below the visualization?
3. I've already started updating and simplifying the color scheme to fit with @jhnns new logo. I like possibly introducing a dark blue and maybe removing some of the grayscale variations but I'm not sure about adding that green to the base color scheme (although it looks for you only used it for syntax highlighting). Feel free to PR changes to the prism theme.
4. In terms of the Navigation (top banner) personally I prefer the active state we have now rather than the underline. Open to the dark blue background switch though.
5. I really like your design for the tips/warnings (tip as a lightbulb), those can definitely get updated 👍 . We should probably also introduce the fontgen-loader soon so adding icons is easier.
6. The other stuff, i.e. the font changes, increases in padding, changes of alignment etc., I'm not sure is as necessary, esp for now.

If you do open PRs, please try to tackle these things individually so it's easier for us to quickly review, merge, and deploy.

[sokra]

@pastelsky thanks for your great work. I like the direction of this. It would be great if you could split your work into multiple PRs so the details could be discussed there. I would propose these parts, but feel free to choose your own splitting:

• Styling change: colors, font
• Slashpage: new svg, getting started button
• Sidebar
• Getting started guide
• Other spelling/grammar changes

[jhnns]

Can we close this issue as it has been split into sub-issues?

[bebraw]

Yeah, let's close and work in the sub-issues.