{"action":"created","issue":{"url":"https://api.github.com/repos/nodejs/node/issues/2366","labels_url":"https://api.github.com/repos/nodejs/node/issues/2366/labels{/name}","comments_url":"https://api.github.com/repos/nodejs/node/issues/2366/comments","events_url":"https://api.github.com/repos/nodejs/node/issues/2366/events","html_url":"https://github.com/nodejs/node/issues/2366","id":100613901,"number":2366,"title":"Moving the Docs into the documentation repo","user":{"login":"chrisdickinson","id":37303,"avatar_url":"https://avatars.githubusercontent.com/u/37303?v=3","gravatar_id":"","url":"https://api.github.com/users/chrisdickinson","html_url":"https://github.com/chrisdickinson","followers_url":"https://api.github.com/users/chrisdickinson/followers","following_url":"https://api.github.com/users/chrisdickinson/following{/other_user}","gists_url":"https://api.github.com/users/chrisdickinson/gists{/gist_id}","starred_url":"https://api.github.com/users/chrisdickinson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chrisdickinson/subscriptions","organizations_url":"https://api.github.com/users/chrisdickinson/orgs","repos_url":"https://api.github.com/users/chrisdickinson/repos","events_url":"https://api.github.com/users/chrisdickinson/events{/privacy}","received_events_url":"https://api.github.com/users/chrisdickinson/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/nodejs/node/labels/discuss","name":"discuss","color":"02d7e1"},{"url":"https://api.github.com/repos/nodejs/node/labels/doc","name":"doc","color":"006b75"}],"state":"open","locked":false,"assignee":{"login":"chrisdickinson","id":37303,"avatar_url":"https://avatars.githubusercontent.com/u/37303?v=3","gravatar_id":"","url":"https://api.github.com/users/chrisdickinson","html_url":"https://github.com/chrisdickinson","followers_url":"https://api.github.com/users/chrisdickinson/followers","following_url":"https://api.github.com/users/chrisdickinson/following{/other_user}","gists_url":"https://api.github.com/users/chrisdickinson/gists{/gist_id}","starred_url":"https://api.github.com/users/chrisdickinson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chrisdickinson/subscriptions","organizations_url":"https://api.github.com/users/chrisdickinson/orgs","repos_url":"https://api.github.com/users/chrisdickinson/repos","events_url":"https://api.github.com/users/chrisdickinson/events{/privacy}","received_events_url":"https://api.github.com/users/chrisdickinson/received_events","type":"User","site_admin":false},"milestone":{"url":"https://api.github.com/repos/nodejs/node/milestones/10","html_url":"https://github.com/nodejs/node/milestones/4.0.0","labels_url":"https://api.github.com/repos/nodejs/node/milestones/10/labels","id":1232256,"number":10,"title":"4.0.0","description":"","creator":{"login":"Fishrock123","id":1093990,"avatar_url":"https://avatars.githubusercontent.com/u/1093990?v=3","gravatar_id":"","url":"https://api.github.com/users/Fishrock123","html_url":"https://github.com/Fishrock123","followers_url":"https://api.github.com/users/Fishrock123/followers","following_url":"https://api.github.com/users/Fishrock123/following{/other_user}","gists_url":"https://api.github.com/users/Fishrock123/gists{/gist_id}","starred_url":"https://api.github.com/users/Fishrock123/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Fishrock123/subscriptions","organizations_url":"https://api.github.com/users/Fishrock123/orgs","repos_url":"https://api.github.com/users/Fishrock123/repos","events_url":"https://api.github.com/users/Fishrock123/events{/privacy}","received_events_url":"https://api.github.com/users/Fishrock123/received_events","type":"User","site_admin":false},"open_issues":3,"closed_issues":1,"state":"open","created_at":"2015-07-29T19:30:25Z","updated_at":"2015-08-12T19:11:49Z","due_on":"2015-08-31T07:00:00Z","closed_at":null},"comments":3,"created_at":"2015-08-12T19:11:49Z","updated_at":"2015-08-12T19:58:56Z","closed_at":null,"body":"At Node summit, the next steps for the documentation working group were discussed. We decided, after deliberation, that it would be best to pull _all_ documentation, including API docs, into [nodejs/docs](https://github.com/nodejs/docs). We discussed the following scenarios:\r\n\r\n* Keeping _all_ documentation in nodejs/node,\r\n* Keeping just the API docs in nodejs/node, with other docs in nodejs/docs,\r\n* Keeping _all_ documentation in nodejs/docs.\r\n\r\nThe problem with keeping docs in nodejs/node is that every doc team member needs to be a full contributor (r+w access) to the repo, and it was expressed that some don't want that kind of access. Additionally, having to contribute to the main repo could be intimidating to folks wishing to contribute to _just_ the docs. Localization contributors would likely have to fork the repo, also. The argument that tipped the scales in favor of splitting everything out, ultimately, is that the docs group would like to move away from versioned docs and towards embedding versioning information _into_ the docs — that is \"this API was introduced in version X, changed in version Y, deprecated in version Z.\" These evergreen docs remove the need to keep the docs strictly versioned alongside the code.\r\n\r\nThis **does not mean** the PRs to this repo will start being accepted sans docs changes — rather, PRs here should be linked to a PR to the docs repo.\r\n\r\n### specific actions\r\n\r\n*This is a strawman and can be modified.*\r\n\r\n1. PR `doc/api/` from current location in Node repo into the docs repo at `src/reference`.\r\n  1. Doc review and cleanup. This is mostly to get rid of the doctool-isms, not to alter content at this point.\r\n2. In the Node repo, PR the removal of `doc/api` and `doc/api_assets`. Add a `README.md` to `doc/` explaining that the documentation is contained in the docs repo. Remove docs-related tasks in `Makefile`.\r\n3. Change the release build step to copy the docs repo `src/` tree (from latest tag in docs repo) into Node src tree at `doc/` before creating package installers / tarballs.\r\n\r\n### timeline\r\n\r\nWe should be able to start once the docs and website working group meet have a common tool for building the docs — there's a docs WG meeting next Tuesday where we'll check on this progress, and I'll update this issue afterwards.\r\n\r\n### what the world looks like afterwards\r\n\r\n* Documentation team will PR their content into the website repo on a regular basis.\r\n  * Doc team will tag those commits so the build WG can easily find the latest published docs.\r\n* Node PRs concerning documentation should be redirected to the docs repo.\r\n* Node PRs not specifically concerning documentation, but affecting documentation, should contain a link to a corresponding docs PR.\r\n  * Note: Node PRs _probably_ shouldn't be merged until their corresponding docs PRs are merged.\r\n\r\n/cc @nodejs/documentation @nodejs/website @nodejs/build @nodejs/tsc "},"comment":{"url":"https://api.github.com/repos/nodejs/node/issues/comments/130427126","html_url":"https://github.com/nodejs/node/issues/2366#issuecomment-130427126","issue_url":"https://api.github.com/repos/nodejs/node/issues/2366","id":130427126,"user":{"login":"snostorm","id":6534,"avatar_url":"https://avatars.githubusercontent.com/u/6534?v=3","gravatar_id":"","url":"https://api.github.com/users/snostorm","html_url":"https://github.com/snostorm","followers_url":"https://api.github.com/users/snostorm/followers","following_url":"https://api.github.com/users/snostorm/following{/other_user}","gists_url":"https://api.github.com/users/snostorm/gists{/gist_id}","starred_url":"https://api.github.com/users/snostorm/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/snostorm/subscriptions","organizations_url":"https://api.github.com/users/snostorm/orgs","repos_url":"https://api.github.com/users/snostorm/repos","events_url":"https://api.github.com/users/snostorm/events{/privacy}","received_events_url":"https://api.github.com/users/snostorm/received_events","type":"User","site_admin":false},"created_at":"2015-08-12T19:58:56Z","updated_at":"2015-08-12T19:58:56Z","body":"> Change the release build step to copy the docs repo src/ tree (from latest tag in docs repo) into Node src tree at doc/ before creating package installers / tarballs.\r\n\r\n@chrisdickinson not 100% sure if I agree with this. I think that the primary packaging workflows should be changed to no longer bundle API documentation at all, or make it a compile-time/GUI installation/package option which downloads a separate bundle. (On the download page we could provide a link for an offline copy of the docs for convenience as well.)\r\n\r\n I think it just simplifies thing for all teams, avoiding questions like: \"do we re-bundle older versions once every time the docs significantly change, or are they locked to some past state forever?\"\r\n\r\nBut I'm happy for this point to be debated more :)"}}