Revise content architecture

[crandmck]

Once the site has the ability to have a multi-level topic hierarchy -- see issue #214 -- the content needs to be reorganized to make it easier to understand, maintain, and navigate. Here is my suggested reorganization.

• Home
• API Reference
  • 4.x (some existing content moved into Dev Guide)
  • 3.x
• Getting started
  • Installing (new section)
  • Using Express app generator (existing content - revised)
  • Hello World (existing content - revised)
  • Basic routing tutorial (new)
  • FAQ (Some content moved to below section)
• Express Developer’s Guide
  • Routing (new section with info from current API doc, enhanced)
  • Error handling (existing content - revised)
  • Debugging Express (existing content - revised)
  • Express behind proxies (existing content - revised)
  • Moving to Express 4 (existing content)
  • Using components (including Expressjs.org's components, jshttp, and former Connect middleware)
  • Database Integration - MySQL, MongoDB, Redis (new)
• Advanced Topics
  • Developing Express components (formerly middleware)
  • Developing template engines for Express
• Resources
  • Glossary
  • Applications - List of sites that use Express. Update list currently at http://expressjs.com/applications.html.
  • Community - List of community resources: mailing list, etc. (revise current page)
  • Books etc - List of books on Express; also possibly other websites and information resources.

[crandmck]

Per #219, need to add "Glossary" under "Resources". (added to above list 9/23/14)

[hacksparrow]

I think we should include Security and Performance too, under Advanced Topics.

[crandmck]

Yes! Do we have content for that topic?

[hacksparrow]

I can write :)

[crandmck]

@dougwilson We have a planned section for "Components" that is currently empty. Could you please help fill it in, e.g. brief description of "what is a component", links to pillarjs modules, etc. Any pointers or help on this would be appreciated.

There are two relevant articles:

• Using components
• Developing components - in the "Advanced" section.
  Feel free to commit to the menu branch or put info into the GH wiki, whichever you prefer.

[dougwilson]

Sure, though, what is an "Express component" (from the developing article)? Is that just an express middleware?

[hacksparrow]

Introducing another term might be confusing. Here are some questions.

i. What is the purpose of using the term "Express components"?
ii. Is "Express middleware" not enough?
iii. Would components be different from middleware in any way?
iv. When does a middleware become a component?
v. Do we get rid of all mentions of middleware from the docs?

Middleware is already a function, which is a callback function, which is an explicit or implicit route handler. If the term "Express component" is introduced without proper forethought, it could end up creating more confusion.

If we can avoid introducing another term, we should; if we must introduce, it should be well justified.

[dougwilson]

@hacksparrow I agree with you. Right now I'm not 100% sure what an "Express component" even is?

[hacksparrow]

For what I know, components == middleware. Let's hear what Rand has to say.

[Fishrock123]

We have a planned section for "Components" that is currently empty. Could you please help fill it in, e.g. brief description of "what is a component", links to pillarjs modules, etc.

Sounds like he means pillarjs - type modules, i.e. our frameworks components, such as the future Router(s).

[dougwilson]

Sounds like he means pillarjs - type modules, i.e. our frameworks components, such as the future Router(s).

Ah. Those wouldn't be "Express components" and a "how to make one" article doesn't make sense to even be in Express documentation, as they don't build off Express, Express builds off them. It sounds like that lineage was just misunderstood.

[dougwilson]

Actually, nevermind on what I said above; re-reading the OP #216 (comment) it sounds like the "Using components" page is for the pillarjs et al. and "Developing Express components" page really does refer to middleware.

[Fishrock123]

I think middleware should be middleware. No use changing the name now. (We aren't in the front-end haha)

Components should be framework components, and that stuff would belong in the pillarjs docs.

[crandmck]

This terminology was per @altsang ... thought it was a known thing.... Will let Al comment

[altsang]

we have two things - middleware that is now pluggable as regular Node modules that Express uses with the app.use(...) interface, these are the pieces that were pulled out of Connect when the decoupling was complete and then we have other things in express that will be pulled out like the router that aren't "middleware".

Can we generalize as "Express components"? I'm fine with "Express Middleware", but last time I kept referring to middleware to generalize both of these I was getting funny looks 😄

We can have two categories as well - one that references the "middleware' pointing to expressjs.org and the "components" pointing to PillarJS - would that work?

[Fishrock123]

stuff you can shove in app.use / call with a req/res/next signature (or err/req/res/next for error handlers = Middleware
(The functionality of these is basically how Middleware works everywhere)

modules that can be swapped inplace of (or including) pillarjs modules = PillarJS Components

[dougwilson]

Gotcha all. The components are below the level of Express and even below Connect; they transcend Express itself, unlike the middlewares, so calling them "Express components" only makes sense in that "these components are what make up Express" from Express's point of view, but they are outside the scope of Express.

i.m.o calling them "Express components" would be similar to saying we use "Express HTTP".

[crandmck]

OK, so it sounds like "Express components" is not right. So, we have "middleware" (as currently) and "PillarJS components"....? Obviously the doc will describe how to use and write middleware. Do we want to discuss PillarJS components, and how it relates to Express, links to the repos, etc?

[dougwilson]

Do we want to discuss PillarJS components, and how it relates to Express, links to the repos, etc?

So, it's really, I think, undecided right now. If a page where to exist on it, it would be to talk about how Express is made of components and which ones, etc. I have to muse over is this would even be of value to the users who come to Express's site looking for how to build with Express.

[Fishrock123]

I think it will be best to state that it's made of PillarJS components, but we aren't quite there yet, so i wouldn't worry about that sort of thing.

[hacksparrow]

My suggestion:

i. Show how to use middleware - npm and locally created modules.
ii. Show how middleware work and how to write your own middleware.
iii. List well-written Node package middleware for various purposes - expressjs and pillarjs among others.

HTTPJS / PillarJS should not be menu items, it will only confuse the users. Their modules can be listed under point iii.

[crandmck]

Sounds good. So I think we should have a "Middleware" topic under "Guide" for i. and ii. above (replacing "Using Components") in my original outline. Should iii. be a part of this topic, or a separate topic? If separate, would it be best to keep under "Guide" or put elsewhere?

[hacksparrow]

iii looks like something which should go under Resources.

[crandmck]

With update of the site, closing this issue. If there are specific issues with the organization, they should be raised in individual issues.