[epic] Documentation work

[phated]

For gulp 4, we are going to be converting the documentation to gitbook and hosting on gulpjs.com.

The list of things that need to be done:

• Decide on and finalize a folder structure
• Update docs to match completed docs in other modules (vinyl-fs, vinyl, undertaker, etc)
• Finish docs in other modules that need completion (bach)
• Cleanup recipes, make sure they work with 4.0 and are consistent with each other (superseded by [Docs] Recipes #2164)
• Docusaurus setup for the website (ref Docusaurus theme for the gulp website gulpjs.github.io#31)
• Tooling for inlining docs (makes other items easier but not mandatory - ref tools to mirror docs #1446)

Ref #1465 (comment)

[phated]

We will need a gitbook plugin that fetches a markdown file from github and clips out a section based on a header. Ref #1446

[phated]

Should be able to put the book.json in the docs/ directory and use GITBOOK_DIR environment variable to point at that directory. This keeps the root of the project a bit more clean. Ref https://github.com/GitbookIO/gitbook-cli/blob/master/lib/config.js#L6

[phated]

It looks like all gitbook filters are set to be async, a promise just needs to be returned. That should make it easy to implement the plugin that fetches docs from other projects. Ref https://github.com/GitbookIO/gitbook/blob/master/lib/template/index.js#L104-L114

[phated]

Example directory structure at https://github.com/reactjs/redux/tree/master/docs

[phated]

We might also want to look into https://github.com/GitbookIO/plugin-versions to support old or future versions of the docs.

[phated]

Documentation for custom theming: http://toolchain.gitbook.com/themes/

[wesbos]

I can't take this 100% on but I'd love to help with the docs.

[phated]

@wesbos awesome! I started a branch at https://github.com/gulpjs/gulp/tree/new-docs but I don't like mirroring the docs in a .docs/ directory. I'm not sure of a better way to handle templating (which I think is needed to pull in external docs from libraries like vinyl-fs, node-glob, etc). Any thoughts?

[herrbischoff]

I'd also like to help with docs.

[phated]

In the short term, I think we should just inline docs by hand to the 4.0 branch. I'm not very happy with the new-docs branch.

[herrbischoff]

Alright, just let me know what exactly I should do and I'll start.

[phated]

I moved the .docs/ directory back to docs/ in the new-docs branch. Any improvements (structure, content, etc) are welcome. Best place to start is to look at the respective projects and see if their documentation is better (I've improved some of it) than what is currently in new-docs and update/improve it.

[phated]

Renamed this "epic" and updated the main issue to have a list of things that need to get done. Will add stuff as it comes up.

[erikkemperman]

@phated Maybe this is a moot question given this issue, but I just noticed that there are currently two CLI.md docs, one here and one over at gulp-cli. The latter one seems older / outdated (meld tells me the one here has additions that the gulp-cli one doesn't) but that's the one which is fed into marked-man...

[phated]

@erikkemperman the CLI docs need to be pulled from gulp-cli master branch (either the readme or https://github.com/gulpjs/gulp-cli/blob/master/docs/CLI.md)

[revelt]

Also, we should add instructions to v.4 docs how to actually install gulp v.4, because currently npm install --save-dev gulp will install v.3.9.1, yet this instruction is currently given on "https://github.com/gulpjs/gulp/blob/4.0/docs/README.md > Getting Started"

[salmanwaheed]

We should do

On Thu, Feb 2, 2017 at 4:26 PM Roy Reveltas ***@***.***> wrote: Also, we should add instructions to v.4 docs how to actually install gulp v.4, because currently npm install --save-dev gulp will install v.3.9.1, yet this instruction is currently given on " https://github.com/gulpjs/gulp/blob/4.0/docs/README.md > Getting Started" — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#1595 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AO8bOHqMsLn_1_4irmWMqQ_VSIM5ZI4uks5rYctegaJpZM4IAhv0> .

-- Sent from IPhone

[phated]

I think we can use something like https://github.com/jonschlinkert/section-matter to help define where information for each section comes from.

[jonschlinkert]

to help define where information for each section comes from.

Oh interesting... let me know if you think of other ways to delimit the sections. I wasn't very creative with the defaults. I'd be happy to implement something more flexible if necessary. Ideas welcome.

[avegancafe]

Is there anything that we can do to help out with the doc work? I saw this comment, not sure if there's anything we as a community can be doing to help push it across the finish line though

[phated]

@kyleholzinger basically, all of the documentation needs to be rewritten. As I was finishing up all our dependencies (and sub-dependencies), I made sure to document them completely, so the effort is to compile all the docs and improve them for the "gulp context".

I'd love to have an automated way to pull docs from those repos but I don't see a clean way for that to happen, so we'll probably just get this done manually.

I also believe that the recipes need to be cleaned up (some are very complex and people seem to just copy them verbatim) and more recipes should probably be created for new gulp 4 features.

[phated]

I'd also like to have an official migration guide but that's tracked in #861

[avegancafe]

@phated you could probably write a little script to pull all the readme's from all our deps and sub-debs though not sure if there's an easy way to know which ones to pull (it'd be a lot of readme's if we did all of them haha). Is there a list of any of the ones that you documented publically available? Sounds like an easy win

[phated]

@kyleholzinger it's going to be much more complicated than that and would probably need to involve front-matter for each section to replace variables and stuff (e.g. in vinyl-fs, the examples use vfs.src/vfs.dest but those would need to become gulp.src/gulp.dest) in the gulp repo.

[phated]

hey everyone, we're still looking for help improving the docs for 4.0 - would love any sort of help!

[selrond]

@phated I could probably help with something - what could it be?

[icarter09]

@phated are you still needing help with improving the v4.0 docs?

[phated]

I'm going to close this since we have the Getting Started and API docs done. We already have another issue (#2164) opened for Recipes and I'll be creating a couple other issues for other pieces that still need to be worked on.