Initial gulp Documentation

[travm]

Here's some of the initial gulp documentation for writing tasks (and a few other additions). There is a lot more to be done, but this should get us started.

With all the discussions going on, I'm unsure if this is the approved way of organizing this content. This was written using the initially approved content base by @rowoot.

[dashed]

@travm You don't mind that I flesh out things in this manner?

[dashed]

@contra Would you like to review these md docs?

[travm]

@dashed Not at all, I appreciate the help! It may be better to wait for it to be merged and then fork the main repo and submit a PR from your fork with your changes.

I'm wondering what would be the best way to collaborate on the docs. @addyosmani How would you prefer we update and submit changes to the documentation? I know organization discussions are still taking place and I don't want to get things started in the wrong direction.

[dashed]

@travm I should probably do a PR on your fork of the repo?

[dashed]

Also https://stackedit.io/ would be super useful for this.

[sindresorhus]

Node.js

[sindresorhus]

Also need some mention of streams, concurrency, and running tasks synchronously and task dependencies.

// @contra

[yocontra]

Check out the wiki again btw if you haven't seen it in a while - it has changed quite a bit and has a lot more info

[travm]

Thanks everyone!

@sindresorhus and @dashed A lot of good points. I'll correct these asap.

@contra Thanks for letting me know. I hadn't seen the updates. Those recipes will help, especially the Mocha one as we need a testing example.

What is the best practice with documentation projects like this? Should I close the PR, resolve these issues and the submit another? Any guidance would be appreciated!

cc @addyosmani

[sindresorhus]

@travm just push more commits to this PR when you're ready and we'll squash it at the end ;)

[travm]

@sindresorhus Much appreciated. :) I'll get these fixed after work this evening and add in the remaining tasks.

[dashed]

@travm I only looked through the beginning md docs. I'll need to set aside some time to look through the rest extensively.

[addyosmani]

As @sindresorhus has already mentioned, great work. We can continue iterating on this PR and just squash your commits at the end of the process once you're ready :)

[travm]

Okay, I think that should cover most of the initial corrections. I apologize if I missed a few. LiveReload section has been fleshed out a bit more, but may need to be further explained.

To do:

• Streams
• .pipe()
• Testing Task
• Deployment
• Advanced Tasks Section?
• Using Config Files (gulp Issue #120)

[0x-r4bbit]

@addyosmani @sindresorhus what do you guys think of the little convention to only use one line per sentence and each sentence a new line.

So a sentence like

I am a sentence and I can be very long. I am another sentence and I'm short.

would be written as

I am a sentence and I can be very long.
I am another sentence and I'm short.

This makes it easier to see diffs in commits etc..

[sindresorhus]

@PascalPrecht no, and github now support wrapping lines in diffs: https://github.com/blog/1707-soft-wrapping-on-prose-diffs

[travm]

Streams introduction is complete. Let me know if I should go into more detail. I was afraid of overwhelming readers in the introduction, so I kept it very basic. Added a quick reminder about .pipe() to the first task in the Writing Tasks section.

To do:

• Testing Task (Mocha)
• Deployment
• Advanced Tasks Section?
• Using Config Files (gulp Issue #120)

[dashed]

Streams wereare designed to perform complex operations by using when constructed as a sequence of smaller, single purpose applications (streams?) in a sequence. The idea was that we could stack These applications (streams?) would connect from one end -point to end and a starting-point of another, then pass the output of one application into the input of another. As allowing the passage of the data passes through each application it is to be modified (or analyzed) at each application. and then piped to the next application in the sequence until the stream is complete. As data make their journey through streams, they may have been modified or transformed so as to be indistinguishable from what they have begun to be. This connection of applications is a concept referred to as piping, (comma here) and the collection of pipes as a whole is referred to as the pipechain.

[travm]

Good suggestions and corrections! I'll put some more thought into this and maybe add an real world example to make it easier to understand for people who are completely new to the idea of streams.

[dashed]

Maybe a quick primer of http://nodejs.org/api/events.html and mention the standard events of streams?

These seem to be frequently used handlers: .on('data'), .on('error'), and .on('end'). At least from my experience with gulp.

[travm]

I'm beginning to wonder if this stream and api information wouldn't better be suited in the Node and npm chapter? Thoughts?

[dashed]

It may mislead readers to its relevance in the book until they read the gulp chapter.

[travm]

Yeah, that's true. Maybe if another tool makes use of streams then we could unify the streams information in the Node chapter and each tool can reference it. For now, It's probably best to remain here.

My biggest fear with including api information this early is that we may overwhelm our target audience who may have never used Node or npm before. What do you think about including more advanced api information and examples after the introductory content?

[addyosmani]

I certainly wouldn't mind seeing more advanced information after the introductory portions.

[travm]

Sounds great! I'll be committing more of the basic documentation for review very soon.

[addyosmani]

@sindresorhus how happy are you with the current state of the chapter?

[sindresorhus]

@addyosmani happy :D

@travm very nice work!

@dashed thanks for reviewing.

[addyosmani]

Thanks so much for all of the hard work @travm!

[travm]

@sindresorhus @addyosmani My pleasure! I'm glad I can help!