{"action":"created","issue":{"url":"https://api.github.com/repos/Kinto/kinto/issues/208","repository_url":"https://api.github.com/repos/Kinto/kinto","labels_url":"https://api.github.com/repos/Kinto/kinto/issues/208/labels{/name}","comments_url":"https://api.github.com/repos/Kinto/kinto/issues/208/comments","events_url":"https://api.github.com/repos/Kinto/kinto/issues/208/events","html_url":"https://github.com/Kinto/kinto/issues/208","id":110021824,"number":208,"title":"Enhance documentation","user":{"login":"almet","id":67073,"avatar_url":"https://avatars.githubusercontent.com/u/67073?v=3","gravatar_id":"","url":"https://api.github.com/users/almet","html_url":"https://github.com/almet","followers_url":"https://api.github.com/users/almet/followers","following_url":"https://api.github.com/users/almet/following{/other_user}","gists_url":"https://api.github.com/users/almet/gists{/gist_id}","starred_url":"https://api.github.com/users/almet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/almet/subscriptions","organizations_url":"https://api.github.com/users/almet/orgs","repos_url":"https://api.github.com/users/almet/repos","events_url":"https://api.github.com/users/almet/events{/privacy}","received_events_url":"https://api.github.com/users/almet/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/Kinto/kinto/labels/documentation","name":"documentation","color":"207de5"},{"url":"https://api.github.com/repos/Kinto/kinto/labels/in%20progress","name":"in progress","color":"ededed"}],"state":"open","locked":false,"assignee":{"login":"leplatrem","id":546692,"avatar_url":"https://avatars.githubusercontent.com/u/546692?v=3","gravatar_id":"","url":"https://api.github.com/users/leplatrem","html_url":"https://github.com/leplatrem","followers_url":"https://api.github.com/users/leplatrem/followers","following_url":"https://api.github.com/users/leplatrem/following{/other_user}","gists_url":"https://api.github.com/users/leplatrem/gists{/gist_id}","starred_url":"https://api.github.com/users/leplatrem/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/leplatrem/subscriptions","organizations_url":"https://api.github.com/users/leplatrem/orgs","repos_url":"https://api.github.com/users/leplatrem/repos","events_url":"https://api.github.com/users/leplatrem/events{/privacy}","received_events_url":"https://api.github.com/users/leplatrem/received_events","type":"User","site_admin":false},"milestone":null,"comments":10,"created_at":"2015-10-06T14:36:35Z","updated_at":"2016-05-02T10:58:10Z","closed_at":null,"body":"I've spent some time doing a review of our actual documentation with @JeremiePat. Here are the outcomes of the discussion:\r\n\r\nIndex:\r\n- The order of the section matters. It should be Overview, Concepts, Community and then Tutorials, Configuration and APIs;\r\n- The menu on the left should be in the same order than these sections.\r\n\r\nOverview:\r\n- The FAQ should be separated from the overview page, and be linked from the the index;\r\n- The comparison table should be in the FAQ page and not in the overview;\r\n\r\nTutorial:\r\n- There is no installation tutorial.\r\n- Requests and Responses should be separated.\r\n- Is this tutorial really useful, since we want people to use our JavaScript client, should we drive them to do so, and let the httpie commands come for implementers who needs them?\r\n- Should we include a Kinto.js tutorial here?\r\n\r\nInstallation:\r\n- There should be some prerequesites in there \"Check your environment\".\r\n\r\nConfiguration:\r\n- Default values could either be in a new column or on a new line;\r\n- Broken links\r\n\r\nAPIs:\r\n- Put the CheatCheet after the list of items;\r\n- Remove the presence of HTTPie command line, it's not useful.\r\n- The PATCH description should be made more explicit.\r\n- Retrieving stored records: put the filtering / pagination *after* the API endpoint\r\n\r\nResource endpoints:\r\n- It seems broken: no menu on le left.\r\n\r\nTroubleshooting:\r\n- Should mention the FAQ.\r\n\r\nContributing\r\n- We should add links to the issues categories\r\n- Add a link to the github repository\r\n- Where are the docs ? How do I edit them ?\r\n- the \"hack\" section is broken\r\n- Troubleshooting should be updated: it's duplicated with the previous section\r\n\r\nMisc:\r\n- On RTD, the \"stable\" release actually displays the cliquet documentation\r\n- On RTD, display the stable release and not \"latest\" by default"},"comment":{"url":"https://api.github.com/repos/Kinto/kinto/issues/comments/216199572","html_url":"https://github.com/Kinto/kinto/issues/208#issuecomment-216199572","issue_url":"https://api.github.com/repos/Kinto/kinto/issues/208","id":216199572,"user":{"login":"almet","id":67073,"avatar_url":"https://avatars.githubusercontent.com/u/67073?v=3","gravatar_id":"","url":"https://api.github.com/users/almet","html_url":"https://github.com/almet","followers_url":"https://api.github.com/users/almet/followers","following_url":"https://api.github.com/users/almet/following{/other_user}","gists_url":"https://api.github.com/users/almet/gists{/gist_id}","starred_url":"https://api.github.com/users/almet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/almet/subscriptions","organizations_url":"https://api.github.com/users/almet/orgs","repos_url":"https://api.github.com/users/almet/repos","events_url":"https://api.github.com/users/almet/events{/privacy}","received_events_url":"https://api.github.com/users/almet/received_events","type":"User","site_admin":false},"created_at":"2016-05-02T10:58:10Z","updated_at":"2016-05-02T10:58:10Z","body":"> What does this mean? Remove the commands that demonstrate how to actually make the requests? I think those are useful, so maybe you're talking about something else.\r\n\r\nThat's what I meant, yes. See #502 for more info on this.\r\n\r\n>I don't see any \"community\" section. Was this renamed to \"Contributing\"? Or should there be a new order?\r\n\r\nThere's a big \"Community\" section in the front page, but it's not reflected in the menu on the left: these two should be the same, and in the same order.\r\n\r\n> Resource endpoints are broken\r\n\r\nThey're broken in the sense that if you actually navigate to a specific example, the according section should be highlighted on the left menu, but it's currently not the case. At least the \"API\" section should be highlighted.\r\n\r\n> the \"hack\" section is broken\r\n\r\nI cannot find anymore why it's broken, so let's consider it's ok!"}}