Dev - Information Architecture (Page Groups)

[pastelsky]

The sidebar is getting quite long in a few pages. It would be nice if related items are grouped into some kind of a collection. I'm not sure if this requires a change in antwar or it's just a config change.

eg.

[skipjack]

Adding @pastelsky's design from #285 for reference:

I really like the look of the sidebar here, and I think between this design and some way to better group the pages, we'd definitely have a more fluid ux. Will try to get started on this soon.

[skipjack]

@johnstew from #749 (closed in favor of this issue):

Breaking out the conversation from #743 into its own ticket to discuss possible parent sections and if this is a good idea. Plus need to decide the UI/UX around having a parent section.

Parent Section Ideas:

• Introduction
• Getting started
• Production
• Caching
• Migration
• Code Splitting
• Tree Shaking
• Contributing to Webpack
• React
• Angular
• Extras

[skipjack]

I'm gonna start working on implementing @pastelsky's design (shown above) but I think we still need to discuss our routing structure a bit and agree on an approach for going forward. Here's what I would propose as a "spec" for how we structure /content...

Within the /content directory we have our top-level routes:

1. Top Level: Concepts, Guides, Documentation, etc.

There are also some others in the top level of the directory but that are currently displayed at the second level of our routing structure even though the directory structure doesn't match. If we're happy with the way it's displayed I think we should create a Top Level Documentation folder and these underneath:

2. Second Level: Configuration, Development, Loaders, Plugins etc.

Note: I'm only listing the ones under Documentation but any directories nested under the other Top Level ones like Concepts would be allowed as well.

One more level of nesting would be allowed, to group the individual pages within the sidebar as originally discussed in this issue. Here are some of the ones @johnstew proposed for the Guides section:

3. Third Level: Introduction, Getting Started, Production, Caching, etc.

Note: These would be a mix of files and directories. As @pastelsky's design shows, individual files would be displayed normally while others would be displayed after the group name

To sum it up here's the list all together, along with how/where each level would be displayed...

1. Top Level: Concepts, Guides, Documentation, etc.
   • Displayed in the Navigation bar along with links to the blog, github, opencollective, etc.
2. Second Level: Configuration, Development, Loaders, Plugins etc.
   • Displayed the Navigation submenu under it's parent
3. Third Level: Introduction, Getting Started, Production, Caching, etc.
   • Displayed in the Sidebar as pages and groups of pages

Note: There is kind of a last level which would be the anchor routing within pages (already displayed in the sidebar.

Another Note: It would probably be useful in certain sections to bypass the second level and go straight to the third. For example, if Concepts doesn't need Navigation bar sublinks we could somehow flag it so it's children are treated as the third level. Or maybe we can determine this automatically by looking for an index.md or something.

@webpack/documentation-team @johnstew @pastelsky let me know your thoughts. Whether or not we follow what I proposed above, a tweaked version of it, or something completely different, I do think it would be extremely valuable to outline some rules and expectations for how we lay things out. It should make implementation and other things much easier.

I'd be more than happy to get to work on this if we can come to an agreement on how we should lay things out. @bebraw I'm guessing there will be some things I might need your help on but, iirc, I think antwar can already handle nesting directories already and we'd just have to handle each level of children in the sections object a certain way, correct?

[bebraw]

I'm guessing there will be some things I might need your help on but, iirc, I think antwar can already handle nesting directories already and we'd just have to handle each level of children in the sections object a certain way, correct?

It can map an arbitrary directory structure to a site, yeah, but we can likely refine it to get a nice solution going on.

---

A combination of manual/automatic link generation seems like a good way to me when it comes to layout. Especially second level links can be figured out based on the context.

[skipjack]

Quick status update...

• Sidebar redesign is done (Sidebar Redesign #1046) although we'll have to make a some small tweaks to support in section groups. I already have an idea of how to approach this.
• I'm working on some routing and /content structure tweaks but grouping within a section is likely blocked by Reflect Content Structure in Routing Structure antwarjs/antwar#124. We could do something similar to the sort in the markdown variables, but that seems like it would be a pain to maintain.

I'd like to get the structure and routing cleaned up and more in sync before going too much further with this. @johnstew once we get a better framework in place, would you be interested in going through and grouping the pages within sections, maybe starting with guides seeing as you already laid that out?

[johnstew]

@skipjack yeah I can check out what I wrote up for guides and see how that compares to what's on there now. I'll focus on getting that done first then go from there for the other sections on the site. Sound good?

[skipjack]

@johnstew sounds great, yea maybe you can share your ideas for how to group each section so we'll have a nice plan laid out by the time we have the groundwork in place to do it.

I should be submitting a PR sometime this week to sync up our routes and content more, however the in-section grouping is still blocked by antwarjs/antwar#124 unless we want to go with the group markdown variable.

[skipjack]

@johnstew btw, what do you think of levels I proposed above? Sound reasonable?

[johnstew]

@skipjack wow sorry for delay been really busy lately. I'm gonna take a stab at this though for the guides section. The levels above make sense to me. Tell me if I got it wrong below.

SubNav

• General
• Production
• React
• Angular
• Other

Sidebar - General

• Getting Started
• Installation
• Code Splitting
  • CSS
  • Libraries
  • Async
• Development
  • Vagrant
• Dependency Management
• Shimming
• Asset Management
• Authoring Libraries
• Environment Variables
• Public Path
• Tree Shaking

Sidebar - Production

• Building for Production
• Caching

Sidebar - React

• HMR
• Lazy Loading

Sidebar - Angular

Sidebar - Other

• Webpack & Typescript
• Integration with Test Runners
• Integration with Task Runners

I'm sure I'm missing some things here but I think some of the above makes sense. I thought we had Angular guides in there at some point. 🤔

Anyways, I think having some more guides around React and Angular would be beneficial. Also integrating with test runners and task runners would be a good idea as well.

Open to suggestions here.

[skipjack]

wow sorry for delay been really busy lately.

No worries, glad to have your help whenever.

As to what you've laid out... yea so the grouping we've talked about within the guides could either be at the second level (navigation submenu) or pushed to the sidebar. Currently we don't have support for grouping pages within the sidebar but I hope to get it to that place. It would likely look similar to what @pastelsky laid out:

Essentially you could have multiple "groups" of pages within the sidebar, similar to how react's sidebar is laid out. So your General, Production, React, etc. sections could be groups within the sidebar without adding a new subnav under Guides in the top banner. Not saying this is the way to go, just what was originally proposed in the issue. With either approach though, until we port to phenomic or antwarjs/antwar#124 is done, we'd have to add a lot more configuration to start grouping by directory.

In terms of the way you grouped things, looks pretty good. I'm not sure how I feel about the React and Angular sections. I think for the most part, it'd be better for us not to do too much framework-specific documentation and instead link out to external blogs and whatnot for this. There's already so much to manage just in terms of documenting webpack's feature set, that adding multiple pages for how to use it with other tools seems like a bit much to me. I think small examples here and there are ok but dedicating entire directories would be too much. For that reason I'd probably lean more towards having it like this for guides:

General

• ...

Production

• ...

Development

• Hot Module Replacement
• Lazy Loading

Other

• ...

Or even splitting Development into Hot Module Replacement and Lazy Loading with multiple pages underneath if necessary. What do you think? Also maybe the tree shaking guide should go in the Production section?

[skipjack]

Ok I'm going to close as this has gotten a bit dated and re-open a new issue with all the key points from here.