Webpack 2 Documentation Project Wants You
As mentioned in the earlier post, webpack 2 is getting close. There is one big obstacle though, documentation. The current documentation is great if you already understand webpack. But if you are just starting to delve into the tool, it’s a less-than-desirable experience.
This is actually the reason why I started the SurviveJS effort. One important part of it is a free book on webpack. A part of the income of the commercial version supports the webpack project directly.
New Version → New Documentation
In order to make webpack both more approachable and usable, we have decided to redevelop the documentation. webpack is going to get a new site with new design.
This is where you come in. We need your help to shape the content and learning experience. This work happens in stages:
- First we will draft topics through the issue tracker of the new site that contains stubs for the required content. The issues will be used for collecting ideas related to each chapter so feel free to chime in.
- When we have agreed on basic ideas to cover per chapter, I expect people will own chapters by commenting at GitHub and commit to writing. I will most likely write quite a few myself.
- Once chapters have been owned, the hard work begins and you should actually write an initial chapter and submit a pull request for it. The content doesn’t have to be perfect as it can be improved in the editing phase.
- After there is content to review, I expect people (and me) to go through it and submit further pull requests to fix and improve it further.
- When the documentation and the site is looking good enough, we’ll publish webpack 2 and enjoy the improved version.
Even though there is a lot of content to develop, not everything of it has to be developed from scratch. A part of the current documentation can be reused and rewritten in a more approachable form. The webpack issue tracker and Stack Overflow can support the work as well. Often the same problems repeat and you’ll start seeing patterns.
To keep it focused, I expect we’ll be linking to existing resources that go further and support the chapters.
If you want to discuss the effort, feel free to join us at the documentation gitter.
Better Developer Experience → Less to Document
I believe just improving the documentation is not enough. We want to help you when you mess up too!
Probably the biggest step towards this would be to document the webpack configuration schema at the core level. webpack-validator already does something like this. There is also a TypeScript definition available (with a 2.x version to come).
“Developers, Doc Writers, UX Designers, Interaction Designers, Schema Writers, TypeScript Definition experts: We want you!”
In a perfect world…
If we had a well documented schema, we could implement nice tooling and documentation on top of that through introspection. Based on this, I believe putting effort towards an official schema would make a lot of sense. Not all documentation work is about writing. Sometimes it’s about developing stronger tooling.
Conclusion
Even if you don’t consider yourself a writer, I am sure you have something to contribute. As a user of the current documentation you most likely know about its pain points. Developers, Doc Writers, UX Designers, Interaction Designers, Schema Writers: We want you!
Comment at the chapter stubs at the issue tracker of the documentation effort or create new issues if there’s something crucial missing. This will get us to a stable release of the long awaited webpack 2.
