Getting Started documentation #2182
Conversation
phated
requested review from
jonschlinkert,
yocontra,
callumacrae,
doowb and
stephenlacy
|
Also posing an open question about whether or not to include documentation/usage of |
| if (file.isBuffer()) { | ||
| const code = uglify.minify(file.contents.toString()) | ||
| file.contents = Buffer.from(code) | ||
| } |
There was a problem hiding this comment.
@phated, this is probably missing cb(null, file) if I'm not mistaken.
To me this would mostly depend on whether you consider using Anyway, great rewrite so far! Would you appreciate help on specific topics now? |
| ``` | ||
|
|
||
| ### Verify your gulp versions | ||
| ```sh |
There was a problem hiding this comment.
This would probably need some instructions on what to do with output.
There was a problem hiding this comment.
I think the assumption was that the output should look like the screenshot otherwise you need to do the steps again but maybe that's a poor assumption to make.
| ); | ||
| ``` | ||
|
|
||
| When a composed operation is run, each task will be executed every time it was referenced. For example, a `clean` task referenced before two different tasks would be run twice and lead to undesired results. Tasks can be wrapped with the [async-once][async-once] module if this **(not recommended)** pattern is needed. |
There was a problem hiding this comment.
Is there a recommended pattern for the same problem? Otherwise I think this note isn't very helpful.
There was a problem hiding this comment.
This is a pattern that people migrating from 3.x might encounter so I thought it was worth mentioning that they can use async-once but the "right way" to do it would be to restructure your tasks so the task was only specified once - the pattern recommended throughout the document.
I'm open to adjusting the language but I think this is worthwhile enough to keep.
It should be the default going forward (and switched to
I like this idea. I'll discuss with @janiceilene |
|
Ping - still looking for y'all to review. |
|
I did a review of the code vs documentation blocks and did not notice any issues that were not mentioned before. Do we want to show an example of a synchronous task as well as stating that it should not be used? |
|
Alright all, I've done a final pass and caught some things that I didn't like. I've also made the fixes suggested so I'm going to get this merged. |
This is the beginning of our full documentation rewrite. It is meant to be the "Getting Started" section on the upcoming docs website with a target audience of:
It is meant to be read in numerical order (the filenames start with 1,2,3,etc).
Any feedback is very much welcomed and appreciated.
cc @stevelacy @contra @terinjokes @jonschlinkert @doowb @callumacrae @demurgos