{"action":"created","issue":{"url":"https://api.github.com/repos/googlecartographer/cartographer_ros/issues/952","repository_url":"https://api.github.com/repos/googlecartographer/cartographer_ros","labels_url":"https://api.github.com/repos/googlecartographer/cartographer_ros/issues/952/labels{/name}","comments_url":"https://api.github.com/repos/googlecartographer/cartographer_ros/issues/952/comments","events_url":"https://api.github.com/repos/googlecartographer/cartographer_ros/issues/952/events","html_url":"https://github.com/googlecartographer/cartographer_ros/pull/952","id":344443959,"node_id":"MDExOlB1bGxSZXF1ZXN0MjAzODM3NTY2","number":952,"title":"Rework the documentation as a step-by-step guide","user":{"login":"FlorentRevest","id":908424,"node_id":"MDQ6VXNlcjkwODQyNA==","avatar_url":"https://avatars0.githubusercontent.com/u/908424?v=4","gravatar_id":"","url":"https://api.github.com/users/FlorentRevest","html_url":"https://github.com/FlorentRevest","followers_url":"https://api.github.com/users/FlorentRevest/followers","following_url":"https://api.github.com/users/FlorentRevest/following{/other_user}","gists_url":"https://api.github.com/users/FlorentRevest/gists{/gist_id}","starred_url":"https://api.github.com/users/FlorentRevest/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/FlorentRevest/subscriptions","organizations_url":"https://api.github.com/users/FlorentRevest/orgs","repos_url":"https://api.github.com/users/FlorentRevest/repos","events_url":"https://api.github.com/users/FlorentRevest/events{/privacy}","received_events_url":"https://api.github.com/users/FlorentRevest/received_events","type":"User","site_admin":false},"labels":[{"id":418857710,"node_id":"MDU6TGFiZWw0MTg4NTc3MTA=","url":"https://api.github.com/repos/googlecartographer/cartographer_ros/labels/cla:%20no","name":"cla: no","color":"ee0701","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":1,"created_at":"2018-07-25T13:29:14Z","updated_at":"2018-07-25T13:30:26Z","closed_at":null,"author_association":"NONE","pull_request":{"url":"https://api.github.com/repos/googlecartographer/cartographer_ros/pulls/952","html_url":"https://github.com/googlecartographer/cartographer_ros/pull/952","diff_url":"https://github.com/googlecartographer/cartographer_ros/pull/952.diff","patch_url":"https://github.com/googlecartographer/cartographer_ros/pull/952.patch"},"body":"This restructures the doc as a tutorial leading newcomers to becoming experimented users.\r\n\r\nIt adds pages on:\r\n - how to get started with Cartographer on a new .bag\r\n - how Cartographer works and can be tuned step-by-step\r\n - how to use \"extra\" features of Cartographer\r\n - how to contribute to Cartographer\r\n\r\nIt also provides some cosmethic changes with: new titles, non-indented code blocks, various illustrations, reworked paragraphs for clarity..."},"comment":{"url":"https://api.github.com/repos/googlecartographer/cartographer_ros/issues/comments/407754556","html_url":"https://github.com/googlecartographer/cartographer_ros/pull/952#issuecomment-407754556","issue_url":"https://api.github.com/repos/googlecartographer/cartographer_ros/issues/952","id":407754556,"node_id":"MDEyOklzc3VlQ29tbWVudDQwNzc1NDU1Ng==","user":{"login":"FlorentRevest","id":908424,"node_id":"MDQ6VXNlcjkwODQyNA==","avatar_url":"https://avatars0.githubusercontent.com/u/908424?v=4","gravatar_id":"","url":"https://api.github.com/users/FlorentRevest","html_url":"https://github.com/FlorentRevest","followers_url":"https://api.github.com/users/FlorentRevest/followers","following_url":"https://api.github.com/users/FlorentRevest/following{/other_user}","gists_url":"https://api.github.com/users/FlorentRevest/gists{/gist_id}","starred_url":"https://api.github.com/users/FlorentRevest/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/FlorentRevest/subscriptions","organizations_url":"https://api.github.com/users/FlorentRevest/orgs","repos_url":"https://api.github.com/users/FlorentRevest/repos","events_url":"https://api.github.com/users/FlorentRevest/events{/privacy}","received_events_url":"https://api.github.com/users/FlorentRevest/received_events","type":"User","site_admin":false},"created_at":"2018-07-25T13:30:26Z","updated_at":"2018-07-25T13:30:26Z","author_association":"NONE","body":"Hi there!\r\n\r\nAs part of an internship for @EasyMile, I've been in charge of investigating various 3D SLAM algorithms for autonomous driving.\r\nCartographer caught my attention and I was led to do a bunch of experiments with it for the past couple of weeks. I started out as a complete ROS and SLAM newbie and I think I stumbled upon just enough difficulties to get a global overview of Cartographer and identify some problems with its documentation.\r\n\r\nI was able to find most of the info I needed spread across Cartographer's source code, paper, GitHub issues, PRs, RFCs, Open House slides, commit log and documentation. It is relatively easy to find what most of the parameters are and do but I found it quite hard to \"connect the dots\" and see the bigger picture of how the many subsystems relate to each others. This led me to believe that information around Cartographer currently *lacks structure*.\r\n\r\nWhile looking at GitHub issues, I was also able to isolate a few things that you keep on repeating over and over again when users want to get started with Cartographer. (for instance: rosbag validation, ``num_accumulated_range_data``, how to report an issue properly and so on...) I believe it also underlines a *lack of documentation* for some of the basic features Cartographer has to offer.\r\n\r\nWhen looking at the documentation, I also found out that some parts were *out of date*. For instance, the supported ROS distributions or the .lua configuration reference or the ROS API (which I haven't changed because there is another pending PR for this).\r\n\r\nTherefore, I decided to address those issues by writing down the knowledge I have gathered and contribute it back to the project.\r\n\r\n- the first goal of this PR is to restructure the current doc from a \"reference documentation\" (with only sparse and low level pieces of information) to a \"zero to hero guide\" (a structured step-by-step tutorial for both newcomers and experimented users)\r\n  I took some liberty to rework the current documentation to propose a structure that makes sense to me.\r\n  You could, of course, disagree with those changes and propose something else.\r\n- the second goal of this PR is to provide in-depth information on how to get started with Cartographer and how to understand its parameters.\r\n  This led to the creation of the \"Running Cartographer ROS on your own bag\" page explaining how to get started with Cartographer and the \"Algorithm walkthrough\" page providing a step-by-step guide to Cartographer *with tuning in mind*.\r\n- the rest of this PR is either cosmetic (title changes for clarity) or provides some basic conveniences (a short contributor guide or pointers to advanced features such as gRPC, IMU calibration and so on...)\r\n\r\nThe \"Algorithm walkthrough\" page is quite ambitious: I'm sure I failed to understand and explain some of the most intertwined concepts used in Cartographer. (for instance: I think I still have troubles understanding the structure of hybrid probability grids) I really hope that your review will pinpoint the parts I could have misunderstood and help me understand what still isn't clear to me. So please let me know if you notice anything wrong and I'll do my best to correct the PR accordingly.\r\n\r\nThanks a lot!\r\n\r\nP.S: CLA was supposed to be signed by the company already, I'll check it out.\r\n\r\nP.S 2: On a more personal note, I also happen to be an open-source project maintainer in my free time and I found Cartographer's openness remarkable. The way you handle Open House sessions and RFCs blew me away, congratulations! If you ever happen to go to FOSDEM, I'll make sure I'll buy you a beer."}}
{"actor":{"display_login":"FlorentRevest"}}