{"action":"created","issue":{"url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/issues/626","repository_url":"https://api.github.com/repos/FakeItEasy/FakeItEasy","labels_url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/issues/626/labels{/name}","comments_url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/issues/626/comments","events_url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/issues/626/events","html_url":"https://github.com/FakeItEasy/FakeItEasy/issues/626","id":140160267,"number":626,"title":"move documentation from wiki to git","user":{"login":"blairconrad","id":3275797,"avatar_url":"https://avatars.githubusercontent.com/u/3275797?v=3","gravatar_id":"","url":"https://api.github.com/users/blairconrad","html_url":"https://github.com/blairconrad","followers_url":"https://api.github.com/users/blairconrad/followers","following_url":"https://api.github.com/users/blairconrad/following{/other_user}","gists_url":"https://api.github.com/users/blairconrad/gists{/gist_id}","starred_url":"https://api.github.com/users/blairconrad/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/blairconrad/subscriptions","organizations_url":"https://api.github.com/users/blairconrad/orgs","repos_url":"https://api.github.com/users/blairconrad/repos","events_url":"https://api.github.com/users/blairconrad/events{/privacy}","received_events_url":"https://api.github.com/users/blairconrad/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/labels/documentation","name":"documentation","color":"02d7e1"},{"url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/labels/in-progress","name":"in-progress","color":"ededed"},{"url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/labels/P2","name":"P2","color":"732787"}],"state":"open","locked":false,"assignee":{"login":"blairconrad","id":3275797,"avatar_url":"https://avatars.githubusercontent.com/u/3275797?v=3","gravatar_id":"","url":"https://api.github.com/users/blairconrad","html_url":"https://github.com/blairconrad","followers_url":"https://api.github.com/users/blairconrad/followers","following_url":"https://api.github.com/users/blairconrad/following{/other_user}","gists_url":"https://api.github.com/users/blairconrad/gists{/gist_id}","starred_url":"https://api.github.com/users/blairconrad/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/blairconrad/subscriptions","organizations_url":"https://api.github.com/users/blairconrad/orgs","repos_url":"https://api.github.com/users/blairconrad/repos","events_url":"https://api.github.com/users/blairconrad/events{/privacy}","received_events_url":"https://api.github.com/users/blairconrad/received_events","type":"User","site_admin":false},"milestone":{"url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/milestones/18","html_url":"https://github.com/FakeItEasy/FakeItEasy/milestones/2.0.0","labels_url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/milestones/18/labels","id":721682,"number":18,"title":"2.0.0","description":"2.0.0 release","creator":{"login":"blairconrad","id":3275797,"avatar_url":"https://avatars.githubusercontent.com/u/3275797?v=3","gravatar_id":"","url":"https://api.github.com/users/blairconrad","html_url":"https://github.com/blairconrad","followers_url":"https://api.github.com/users/blairconrad/followers","following_url":"https://api.github.com/users/blairconrad/following{/other_user}","gists_url":"https://api.github.com/users/blairconrad/gists{/gist_id}","starred_url":"https://api.github.com/users/blairconrad/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/blairconrad/subscriptions","organizations_url":"https://api.github.com/users/blairconrad/orgs","repos_url":"https://api.github.com/users/blairconrad/repos","events_url":"https://api.github.com/users/blairconrad/events{/privacy}","received_events_url":"https://api.github.com/users/blairconrad/received_events","type":"User","site_admin":false},"open_issues":2,"closed_issues":47,"state":"open","created_at":"2014-07-15T10:38:11Z","updated_at":"2016-03-11T20:01:37Z","due_on":null,"closed_at":null},"comments":19,"created_at":"2016-03-11T11:27:38Z","updated_at":"2016-03-19T23:41:31Z","closed_at":null,"body":"Having the docs in the wiki is convenient, and allows for convenient updates by anyone in the world, but introduces problems keeping the documentation synchronized with the code. This was most apparent during the current long-running 2.0.0 release cycle, but I've noticed it other times as well.\r\nIf we moved the documentation into the code, and used something like [Read the Docs](https://readthedocs.org/) to host our documentation, we'd be able to \r\n\r\n1. Update the documentation at the same time the code was changing. Ideally whoever was contributing a fix or enhancement would also update the documentation, but we could do so in a superseding PR if needed. This would ease our cognitive load, and help reduce the work needed to release a new version - no more scrambling at the last minute to make sure the docs are correct.\r\n2. Make available different versions of the documentation, for those stuck using older versions of the library\r\n3. Not have to worry so much about footnotes or the fancy \"[Version 1.x | Version  2.x]\" selectors on pages.\r\n\r\nI'd be inclined to put product documentation in the source. You know, things that relate directly to using FakeItEasy and may change release by release.\r\nI think keeping the contributor / owner docs in the wiki makes more sense. \r\n\r\nChanges I'd like to make before publishing Please push back if there's anything that doesn't make sense\r\n\r\n- [x] tidy everything up as best I can\r\n- [ ] create separate branches for working on the 1.25.3 and 2.0.0 versions\r\n- [ ] in the 1.25.3 branch, move all the \"in 1.x\" topics to replace their \"unversioned\" twin (see [Raising Events](https://github.com/FakeItEasy/FakeItEasy/wiki/Raising-Events) for a sample, if you don't know what I'm talking about)\r\n- [x] remove from the 2.0.0 documentation all the notes that refer to how things changed between 1.x versions. Like the footnotes on the Bootstrapper page. We'd be making the 2.0.0 documents a clean break from the 1.x version. The 1.25.3 documentation could retain these\r\n- [x] reference to \"Running multithreaded unit tests with FakeItEasy\" from the 2.0.0 version of the \"External Resources\" page. We shouldn't need it.\r\n- [x] remove \"Slow startup time\" from the 2.0.0 documentation. The issues we knew about have been addressed, and there have been no complaints for a long time. With no reason to assume that this will be a problem again, why devote space to it?\r\n- [x] remove \"Upgrading from older versions\" from the 2.0.0 documentation? It handles one very specific task that will need to be done to upgrade from an old version, ignoring nearly everything else."},"comment":{"url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/issues/comments/198809059","html_url":"https://github.com/FakeItEasy/FakeItEasy/issues/626#issuecomment-198809059","issue_url":"https://api.github.com/repos/FakeItEasy/FakeItEasy/issues/626","id":198809059,"user":{"login":"thomaslevesque","id":1864281,"avatar_url":"https://avatars.githubusercontent.com/u/1864281?v=3","gravatar_id":"","url":"https://api.github.com/users/thomaslevesque","html_url":"https://github.com/thomaslevesque","followers_url":"https://api.github.com/users/thomaslevesque/followers","following_url":"https://api.github.com/users/thomaslevesque/following{/other_user}","gists_url":"https://api.github.com/users/thomaslevesque/gists{/gist_id}","starred_url":"https://api.github.com/users/thomaslevesque/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/thomaslevesque/subscriptions","organizations_url":"https://api.github.com/users/thomaslevesque/orgs","repos_url":"https://api.github.com/users/thomaslevesque/repos","events_url":"https://api.github.com/users/thomaslevesque/events{/privacy}","received_events_url":"https://api.github.com/users/thomaslevesque/received_events","type":"User","site_admin":false},"created_at":"2016-03-19T23:41:31Z","updated_at":"2016-03-19T23:41:31Z","body":"Great job @blairconrad!\r\n\r\n> I'm inclined to remove from the 2.0.0 documentation all the notes that refer to how things changed between 1.x versions. Like the footnotes on the Bootstrapper page. We'd be making the 2.0.0 documents a clean break from the 1.x version.\r\n\r\nIt would probably be useful to have a page showing all the changes in 2.0.0, to make it easier for people to migrate to 2.x. If the information is scattered on many different pages, it will be harder to find.\r\n"}}