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?