Open addyosmani opened 10 years ago
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.
@addyosmani Hi there. This looks interesting. Any reasons why things like testing and debugging should be avoided for the first version?
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.
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 :)
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)
Happy to contribute to this project in any way possible.
@rowoot I like this baseline for each section. Looks like @travm has already started using it :)
@travm did raise some good points regarding couple of sections (installation specifics, gotchas/debugging). I have updated the outline based on his feedback.
Proposed a directory structure to organize documents https://github.com/tooling/book-of-modern-frontend-tooling/issues/3#issuecomment-31273800
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:
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?
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.
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?
@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 https://github.com/tooling/book-of-modern-frontend-tooling/issues/9#issuecomment-31289156, 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.
To help organize conversations around planning this project's scope.
Discussions so far
@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.
@rowoot I'm +1 on structure. Tagging in @sindresorhus too in case he has any opinions.
I'm happy with this structure as well. Looking forward to getting started once we get that structure pulled in and approved!
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.
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:
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
@Raynos Possible will be useful to add some information about test coverage, for Karma we have used istanbul - https://github.com/yahoo/istanbul
@gskachkov Yes coverage is awesome! I havn't got a good story for integrating instanbul
with testem
yet :(
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?