Project scope

[addyosmani]

You'll notice that the initial chapters proposed represent a limited list of the material that could be covered on front-end tooling.

There's a lot out there and I think that for the first version, we should avoid looking at topics like debugging, testing with a specific solution (unless its presented as part of the workflow of using one of the tools already on there).

Does anyone massively disagree with this or should we reconsider scope?

[passy]

I wouldn't exclude testing completely. Explaining different tools and strategies could fill a book on its own and should definitely considered to be out of scope. But when I think about the chapters about Grunt and Gulp, a comparison between them by realizing the same workflow with both tools seems quite natural. I think a testing step is quite interesting because it usually runs on top of the build artifacts and separate from the previous build process.

[0x-r4bbit]

@addyosmani Hi there. This looks interesting. Any reasons why things like testing and debugging should be avoided for the first version?

[Garbee]

Do template systems like AngularJS, Ember, Backbone, etc. fit the current scope?

Templates could at least make a good subject for a future milestone if it isn't included with the first.

[addyosmani]

I'd be happy for the book to also capture debugging and testing but it really depends on whether we can find authors to help write that content for the first version. I think they're otherwise totally legit topics.

@Garbee a future milestone would make sense I think :)

[michealbenedict]

Fantastic initiative @addyosmani. I can see how useful such a book can be.

Having said that, to avoid scope creep (and to ensure focussed deliverables), would it make sense to have a canonical set of table of contents for each tool, something along the lines as below:

(updated this based on @travm's suggestion)

• Introduction
  • Why (what problem it solves)
  • How (briefly)
• Getting started
  • Installation (any tool specific installation notes, any specific dependencies else the Node/npm notes should do good)
  • Tool API/CLI command reference (probably, this can be moved as a separate section)
• Tool specific content
  • (this would require scoping by the tool's resident experts)
• Good practices
• Debugging/gotchas (if any, these could also include common installation problems)

Happy to contribute to this project in any way possible.

[addyosmani]

@rowoot I like this baseline for each section. Looks like @travm has already started using it :)

[michealbenedict]

@travm did raise some good points regarding couple of sections (installation specifics, gotchas/debugging). I have updated the outline based on his feedback.

[michealbenedict]

Proposed a directory structure to organize documents #3 (comment)

[michealbenedict]

Moving the project structure conversation from #3 to here.

I have revised the project structure to address a couple of concerns. My proposal is based on the following goals:

1. enable modular chapters (with assets and sections, this gives the ability to iterate on specific chapters and its sections without disrupting other chapters)
2. Support to scale to n tools (Eg, bower, grunt, gulp, etc) and m groups (Eg, dependency management, build, etc)
3. Simplify content organization for the author. Introducing toc.md that heps organize sections as required.

# Example: Overall project structure

├── Gruntfile.js
├── README.md
├── assets // Shared assets
├── chapters
│   ├── dependency-management
│   │   └── bower
│   │       ├── assets // Chapter specific assets
│   │       │   └── s1-awesomeimage.jpg
│   │       ├── getting-started.md
│   │       ├── introduction.md
│   │       ├── references.md
│   │       ├── toc.md
│   │       ├── tool-another-topic.md
│   │       ├── tool-some-awesome-topic.md
│   │       └── troubleshooting.md
│   ├── glossary.md
│   ├── introduction.md
├── dist
└── package.json
...

# Example: chapters/dependency-management/bower/toc.md
* [Introduction](introduction.md)
* [Getting started](getting-started.md)
* [Some awesome topic](topic-some-awesome-topic.md)
* [Another topic](topic-another-topic.md)
* [Troubleshooting](troubleshooting.md)
* [References](references.md)

Thoughts/feedback?

[travm]

I think this will work very well! I'll let the other contributors review and chime in to ensure it will work across the board. Once we can get the base setup and pulled into the main repo, I'll start working on the gulp information right away. Working on some basic examples as we speak.

[addyosmani]

The revised structure is much better :) One question I have is: do we think there's going to be enough content for a per chapter preface that wouldn't overlap with the introduction?

[michealbenedict]

@addyosmani I do agree, these are simply placeholder files at the moment. I have removed the file to minimize the scope.

Secondly, as proposed in my previous #9 (comment), I have templatized this structure in my fork (https://github.com/rowoot/book-of-modern-frontend-tooling/tree/file-structure).

If everyone is ok with this structure, we can start building content around this? @addyosmani and @travm let me know if I need to tag some other folks to help review this.

[michealbenedict]

To help organize conversations around planning this project's scope.

Discussions so far

1. List of chapters (README.md outlines this, would an issue help kickstart discussions to finalize chapters for v1?)
2. Project structure (Project scope #9 (comment))
3. Building (and exporting) the book (Build system #8)
4. Skeleton for Tool specific content (Project scope #9 (comment))

[addyosmani]

@rowoot Good idea re: 1. I've just created #15 for us to track the list of chapters. Would be great to flesh it out a little more to cover the structure that's been proposed in this issue.

[addyosmani]

@rowoot I'm +1 on structure. Tagging in @sindresorhus too in case he has any opinions.

[travm]

I'm happy with this structure as well. Looking forward to getting started once we get that structure pulled in and approved!

[Raynos]

As part of frontend tooling, testing systems like testem or karma are actually really important tools for doing multi browser automated unit tests.

They are probably more important for a frontend development then build systems, since you can just hand code you build system trivially, you can't hand code a multi browser test runner trivially.

[addyosmani]

I agree with your points about the importance of testing (it'll come down to whether we can get commitment from community authors). Would such a testing section just be looking to capture testem and karma?

For anyone that might want to propose other alternatives worth covering, the key features that both Testem and Karma have include:

• Support for running/driving multiple browsers simultaneously, including headless browsers (i.e., PhantomJS)
• Support for the main testing libraries out there - QUnit, Jasmine, Mocha, etc.
• Both will watch the source/test files (that you selectively configure) for changes and automatically re-run tests
• Both provide support for local and CI use
• Both are terminal focused

[Raynos]

The main thing that testem and karma give is a proper frontend TDD flow. The idea you can write some tests, see a terminal go red, write some code, see a terminal go green, repeat is really powerful.

A lot of people don't write tests. Some people write tests but have a test page they have to run with a server and have to manually refresh in multiple browsers, this sucks because both testem and karma tell you the results for all browsers in one page / terminal.

another thing that's cool about testem is tooling, I configured a bash script called testem-browser that I can in any folder that has a test/index.js file and it just does the right thing, zero configuration, zero setup, zero boilerplate.

So big features are

• really easy to run tests in browsers / headless
• zero configuration / boilerplate / setup / hassle, it's really really easy.
• show the results for multiple browsers in a single terminal / web page
• re-runs your test suite on file save enabling a "write test, save. tests fail, write code, save. tests pass" workflow. That workflow only works if the feedback is instant (which it is for fast tests in testem).

[gskachkov]

@Raynos Possible will be useful to add some information about test coverage, for Karma we have used istanbul -
https://github.com/yahoo/istanbul

[Raynos]

@gskachkov Yes coverage is awesome! I havn't got a good story for integrating instanbul with testem yet :(