{"action":"created","issue":{"url":"https://api.github.com/repos/weaveworks/weave/issues/2183","repository_url":"https://api.github.com/repos/weaveworks/weave","labels_url":"https://api.github.com/repos/weaveworks/weave/issues/2183/labels{/name}","comments_url":"https://api.github.com/repos/weaveworks/weave/issues/2183/comments","events_url":"https://api.github.com/repos/weaveworks/weave/issues/2183/events","html_url":"https://github.com/weaveworks/weave/issues/2183","id":148857655,"number":2183,"title":"doc structure is illogical","user":{"login":"rade","id":109109,"avatar_url":"https://avatars.githubusercontent.com/u/109109?v=3","gravatar_id":"","url":"https://api.github.com/users/rade","html_url":"https://github.com/rade","followers_url":"https://api.github.com/users/rade/followers","following_url":"https://api.github.com/users/rade/following{/other_user}","gists_url":"https://api.github.com/users/rade/gists{/gist_id}","starred_url":"https://api.github.com/users/rade/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rade/subscriptions","organizations_url":"https://api.github.com/users/rade/orgs","repos_url":"https://api.github.com/users/rade/repos","events_url":"https://api.github.com/users/rade/events{/privacy}","received_events_url":"https://api.github.com/users/rade/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/weaveworks/weave/labels/chore","name":"chore","color":"207de5"}],"state":"open","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/weaveworks/weave/milestones/22","html_url":"https://github.com/weaveworks/weave/milestones/1.5.0","labels_url":"https://api.github.com/repos/weaveworks/weave/milestones/22/labels","id":1417778,"number":22,"title":"1.5.0","description":"","creator":{"login":"awh","id":1504438,"avatar_url":"https://avatars.githubusercontent.com/u/1504438?v=3","gravatar_id":"","url":"https://api.github.com/users/awh","html_url":"https://github.com/awh","followers_url":"https://api.github.com/users/awh/followers","following_url":"https://api.github.com/users/awh/following{/other_user}","gists_url":"https://api.github.com/users/awh/gists{/gist_id}","starred_url":"https://api.github.com/users/awh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/awh/subscriptions","organizations_url":"https://api.github.com/users/awh/orgs","repos_url":"https://api.github.com/users/awh/repos","events_url":"https://api.github.com/users/awh/events{/privacy}","received_events_url":"https://api.github.com/users/awh/received_events","type":"User","site_admin":false},"open_issues":9,"closed_issues":160,"state":"open","created_at":"2015-11-18T13:00:50Z","updated_at":"2016-04-16T14:33:47Z","due_on":"2016-04-18T23:00:00Z","closed_at":null},"comments":14,"created_at":"2016-04-16T14:33:47Z","updated_at":"2016-04-17T05:42:47Z","closed_at":null,"body":"The top level doc structure is illogical, and contains a few other niggles. Here it is\r\n```\r\n    Introducing Weave Net\r\n    Weave Features\r\n    Installing Weave Net\r\n    Operational Guide\r\n    Using Weave Net – Example\r\n    IP Addresses, Routes and Networks\r\n    Setting Up The Weave Net Docker API Proxy\r\n    Using Fast Datapath\r\n    Using the Weave Net Docker Network Plugin\r\n    Encryption and Weave Net\r\n    How Weave Net Works\r\n    Address Allocation with IP Address Management (IPAM)\r\n    Using WeaveDNS\r\n    Using Weave with Systemd\r\n    Weave Net FAQ\r\n    Troubleshooting Weave Net\r\n    Building Weave Net\r\n```\r\nIssues:\r\n- `Introducing Weave Net` should just be `Introduction`\r\n- `Weave Features` should just be `Features`\r\n- `Installing Weave Net` should just be `Installation`\r\n- `Operational Guide` should be `Operation`\r\n- `Using Weave Net - Example` should be just `Using Weave Net`\r\n- `IP Addresses, Routes and Networks` does not belong at the top level; not sure where it should go; perhaps the Ops Guide or How It Works\r\n- `Using Fast Datapath` should not be at the top level; not sure where it should go; perhaps the Ops Guide\r\n- `Setting Up the Weave Net Docker API Proxy` should just be `Docker API Proxy`\r\n- `Using the Weave net Docker Nework Plugin` should just be `Docker Network Plugin`\r\n- `Encryption and Weave Net` should just be `Encryption` and it should not be at the top level; not sure where it should go; perhaps the Ops Guide\r\n- `How Weave Net Works` should come later\r\n- `Address Allocation with IP Address Management (IPAM)` should just be `IP Address Allocation`\r\n- `Using WeaveDNS` should be `Naming and Discovery`\r\n- `Using Weave with Systemd` does not belong at the top level; Ops Guide is probably the right place for it\r\n- `Weave Net FAQ` should just be `FAQ`\r\n- `Troubleshooting Weave Net` should just be `Troubleshooting`\r\n\r\nSo, with all the above changes applied, here's how the top level would look like\r\n```\r\n    Introduction\r\n    Features\r\n    Installation\r\n    Operation\r\n    Using Weave Net\r\n    Docker API Proxy\r\n    Docker Network Plugin\r\n    IP Address Allocation\r\n    Naming and Discovery\r\n    How Weave Net Works\r\n    FAQ\r\n    Troubleshooting\r\n    Building Weave Net\r\n```"},"comment":{"url":"https://api.github.com/repos/weaveworks/weave/issues/comments/210960507","html_url":"https://github.com/weaveworks/weave/issues/2183#issuecomment-210960507","issue_url":"https://api.github.com/repos/weaveworks/weave/issues/2183","id":210960507,"user":{"login":"rade","id":109109,"avatar_url":"https://avatars.githubusercontent.com/u/109109?v=3","gravatar_id":"","url":"https://api.github.com/users/rade","html_url":"https://github.com/rade","followers_url":"https://api.github.com/users/rade/followers","following_url":"https://api.github.com/users/rade/following{/other_user}","gists_url":"https://api.github.com/users/rade/gists{/gist_id}","starred_url":"https://api.github.com/users/rade/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rade/subscriptions","organizations_url":"https://api.github.com/users/rade/orgs","repos_url":"https://api.github.com/users/rade/repos","events_url":"https://api.github.com/users/rade/events{/privacy}","received_events_url":"https://api.github.com/users/rade/received_events","type":"User","site_admin":false},"created_at":"2016-04-17T05:42:47Z","updated_at":"2016-04-17T05:42:47Z","body":"> How about \"Naming and Discovery with WeaveDNS\"? It's implied that we are talking about containers and services.\r\n\r\nNo, it is not implied. We could be talking about peers, for example.\r\n\r\nAlso, the above is not \"active\".\r\n\r\n>  \"Address allocation with IP Address Management (IPAM)\" <--- this is still an active sentence which is what we're going for here. \r\n\r\nI don't see how that is \"active\", based on the definition you linked to earlier. And the duplication of \"Address\" is awkward.\r\n\r\nAs I said, \"IPAM\" is jargon. So much so that went out of our way to not mention it in commands/options (e.g. we have `--ipalloc-init` not `--ipam-init`). I see no benefit in referring to it in the heading. In fact I would be happy if *none* of our docs mentioned it.\r\n\r\n> I don't think it's entirely necessary to say, \"Exploring Weave Net Features\", since there isn't anything that the user needs to do\r\n\r\nTrue. That is also the case for \"Introducing Weave Net\" - it is not the reader that is doing the introducing.\r\n\r\n> \"Feature Overview\" is ok in this instance. \r\n\r\nThat is not active. Anyway...\r\n\r\n```\r\n    Introducing Weave Net\r\n    Feature Overview\r\n    Installing Weave Net\r\n    Operating Weave Net\r\n    Using Weave Net\r\n    Integrating Docker via the API Proxy\r\n    Integrating Docker via the Network Plugin\r\n    Allocating IP Addresses\r\n    Naming and Discovering Containers and Services\r\n    Understanding how Weave Net Works\r\n    FAQ\r\n    Troubleshooting Weave Net\r\n    Building Weave Net\r\n```\r\n\r\n> What other methods are there besides DNS to discover services? \r\n\r\n- Links and injecting environment variables; which is what Docker used to do.\r\n- Service registries based on the likes of etcd or consul; there are plenty of articles extolling the virtues of that."}}