Configuration Documentation

[sokra]

WIP

[skipjack]

@sokra hey I started working on this page as discussed with @bebraw in #25. I hadn't created a pull request yet as I'm not through the first pass (most of the way through resolve options). You can check out what I have on the api_configuration branch.

Should I just scrap what I've done or do you want me to merge it into this PR? I should be done with the first pass in the next few days. If I merged it into here now, maybe others can review and take on some of the sections that I don't have as much knowledge on (there are TODOs throughout). I have a few ideas re structure too if you're interested.

[sokra]

hi @gregvenech yes we should definitely merge our branches. You may notice that I've only layouted this page but haven't written any content yet.

My idea was to add a code block with the configuration with a short explanation comment and a link to a more detailed section. This way you get a short overview. I also separated basic options from advanced options.

[skipjack]

Sounds good, yea I'll look at it more tonight and try to merge what I have into yours and follow your layout.

[sokra]

@gregvenech merged both branches, we can continue working on that.

[skipjack]

Just added documentation for the rest of resolve and cleaned up a few things...

I like the idea with the linked code although I think the comments can be left out. I just came across something similar which might be another option, i.e. the hover behavior.

A few other thoughts:

• Definitely agree with the Basic/Advanced breakdown and I think there's a variety of ways we can go about it. Maybe the best would be something like a per option or per group expandable advanced section? e.g...

Option | Group of Options

string boolean

Description...

code

Advanced Usage/Options...

This prevents breaking up the option groups (like output and module).

• There's definitely a lot of content to squeeze into this page, should we consider breaking some out into separate pages? Even if we want to keep all the config options here, we could at least separate out Passing a Configuration and External Configuration
• Try to standardize the way we display value types (e.g. string boolean) and defaults for each option. This can probably carry over to other /api sections as well. Already somewhat in the works...

[skipjack]

What do you all think, @bebraw @sokra @TheLarkInn, about breaking template string substitutions into its own section and then referring to it from throughout the rest of the page? It seems like there's a lot of overlap between sections there so this could centralize and dedupe all that in one place.

Again, maybe this is another one that can be broken out into it's own page.

[bebraw]

@gregvenech The way I see it, the function of this page is primarily to work as a quick reference (you want to see what this or that field does). So pushing more advanced info elsewhere could be worthwhile. Curious to hear what others think.

[skipjack]

@webpack/documentation-team I'm willing to break this up as soon as we decide how to we want to do that. I wanted people to have more time to review but maybe we should just start breaking it up first and then hit the TODOs page by page later.

It seems like the original plan for most of this documentation was to split it up into the various pages under /concepts. IMO, and what I originally thought, was that each concept page was going to be a more high-level discussion on the various topics. Personally I think if it is just detailed documentation with examples we should either rename the section or create a new section.

Either way though I'm willing to break this up and pass it on to others for more review and editing.

[bebraw]

What if we pushed the root level documentation for configuration to root level and even linked to it at the navigation? So you would end up with webpack.js.org/configuration and then Configuration | Concepts | How to | API | GitHub at the navigation.

It's literally one of the most important pages so making it prominent wouldn't hurt.

[skipjack]

@bebraw that's exactly what I was thinking. If everyone's good with this I'll make this change tonight.

[sokra]

Concepts | How to | Configuration | API | GitHub

[skipjack]

Starting to break it out. Will finish this up, incorporate the new nav link, and merge tonight.

[skipjack]

Merged... we can review and edit each page in more granular pull requests now.

[pastelsky]

Nice to see documentation for webpack progressing, however I, as a user, am disappointed that some content is being picked up from the existing documentation since it's been confusing to use time and again.

While serving the documentation on a well layed out site might help with the confusion, I really doubt it's going to be any less frustrating to understand the various terminologies used.

For example, sample the current description given for the devServer config -

devServer

This set of options is picked up by webpack-dev-server and can be used to change it's behavior in various ways. Here's a simple example that gzips and serves everything from our /dist directory:

 devServer: {
   contentBase: "dist/",
   compress: true,
   port:9000
 }

When the server is started, there will be a message prior to the list of resolved modules:

 http://localhost:9000/
 webpack result is served from /build/
 webpack is served from dist/

that will give some background on where the server is located and what it's serving.

devServer.contentBase

Tell the server where to serve content from. output.publicPath will also be used to determine where the bundles should be served from.

Note how various terms are used refer to similar things, without a distinction. Here's a brain dump of the questions that pop up in my mind -

1. What is a contentBase? What do you mean by content? How is it different from what webpack builds? Is content different from assets?

2. Why is a contentBase different from a publicPath? They seem to do similar things(or do they?)

3. Why do examples use both \build and \dist directories? Are they exclusive of each other, or was it because the docs were written by different authors?
   webpack is served from \dist - wait what? Why are you serving me webpack?

4. Why have two different places to pass options to devServer? Are the options specified here merged/overwritten by ones I specify while using webpackDevServer in my express server?

[TheLarkInn]

I appreciate you expressing this. So we came to two conclusions:

1. The existing content can be a very helpful 'cheatsheet' for those already familiar with webpack.
2. This is only the first step in the process. We wanted to save work and time involved while still preserving a familiar format for 'well-versed' users. What we now plan to do, is iterate over the quality of the information and provide the 'why' and 'how'. Right now we just have the 'what'.

Hopefully that clarifies things for you!

[skipjack]

Hi @pastelsky, thanks for your feedback. As @TheLarkInn mentioned, this is only the first pass at the configuration documentation and as I said in my last comment anyone is welcome to review, edit and PR any of these sections. As you can see I also left a lot of TODOs throughout these pages on the places that I think are too ambiguous/vague and those that I just didn't have enough background using to rewrite. The reason I merged this a bit early was because we were starting to see overlap between here and Concepts and it was somewhat unwieldy to review as one long document.

What is a contentBase? What do you mean by content? How is it different from what webpack builds? Is content different from assets?

Agreed that some of these are ambiguous. Maybe something like Decide what directory to serve the site from (usually where your index.html file lives).

Why is a contentBase different from a publicPath? They seem to do similar things(or do they?)

They do not, publicPath tells webpack where your webpack output (i.e. anything that went through webpack, not only bundles) in relation to the directory you're serving from (i.e. contentBase).

Why do examples use both \build and \dist directories? Are they exclusive of each other, or was it because the docs were written by different authors? webpack is served from \dist - wait what? Why are you serving me webpack?

They are exclusive of each other. The issue you describe here is more about what the actual webpack-dev-server logs out than how it's documented as I just copied that from an actual dev-server start up process. With that said though, I think digging through and rewriting the documentation will suggest a bunch of places where improvements can be made in the actual tools as well. Aside from the making some of the logging less ambiguous, I think some of the keys for the configuration options can be simplified or clarified as well.

Hope this helps, again please feel free to edit and PR these changes and any others you might have.

[jhnns]

I agree with @pastelsky that mixing terms and examples is a problem. I really like the redux documentation that uses the TODO example throughout the documentation. This makes it easier to read different parts without switching contexts too often.