{"action":"created","issue":{"url":"https://api.github.com/repos/Homebrew/homebrew/issues/47164","labels_url":"https://api.github.com/repos/Homebrew/homebrew/issues/47164/labels{/name}","comments_url":"https://api.github.com/repos/Homebrew/homebrew/issues/47164/comments","events_url":"https://api.github.com/repos/Homebrew/homebrew/issues/47164/events","html_url":"https://github.com/Homebrew/homebrew/issues/47164","id":123058372,"number":47164,"title":"Reorganize documentation with ToC and Paths","user":{"login":"apjanke","id":2618447,"avatar_url":"https://avatars.githubusercontent.com/u/2618447?v=3","gravatar_id":"","url":"https://api.github.com/users/apjanke","html_url":"https://github.com/apjanke","followers_url":"https://api.github.com/users/apjanke/followers","following_url":"https://api.github.com/users/apjanke/following{/other_user}","gists_url":"https://api.github.com/users/apjanke/gists{/gist_id}","starred_url":"https://api.github.com/users/apjanke/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apjanke/subscriptions","organizations_url":"https://api.github.com/users/apjanke/orgs","repos_url":"https://api.github.com/users/apjanke/repos","events_url":"https://api.github.com/users/apjanke/events{/privacy}","received_events_url":"https://api.github.com/users/apjanke/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/Homebrew/homebrew/labels/documentation","name":"documentation","color":"9bde9f"},{"url":"https://api.github.com/repos/Homebrew/homebrew/labels/features","name":"features","color":"DDDDDD"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2015-12-19T03:29:34Z","updated_at":"2016-01-01T03:44:04Z","closed_at":null,"body":"I'd like to reorganize the documentation in [the `share/doc/homebrew` folder](https://github.com/Homebrew/homebrew/tree/master/share/doc/homebrew) to make it easier to read as a whole, and easier to find certain topics in it. Spruce up the formatting a bit.\r\n\r\nRight now it's a little hard to consume as a whole, because the only list of all the topics is the list of filenames in that directory. The main README links to a few of them, but doesn't cover everything, so it's hard to get an overview or determine a path to read through the whole documentation set, like you would with a book.\r\n\r\nItems:\r\n- Add a Table of Contents that includes all the doco pages\r\n - Grouped by subject area, arranged in something like a sensible front-to-back reading order, with more advanced topics later and prerequisites first\r\n - Traverse the current links and see if all the pages are actually reachable through the current structure, without resorting to the file listing\r\n- Add a couple \"Paths\" that list pages under a certain topic or use case\r\n- Review all the pages and restructure them if needed for clarity or to remove redundancy\r\n- Change backtick `\\`\\`` markup for example code to `<code>...</code>` to allow nesting bold and italic formatting inside the monospace-font code blocks (to indicate placeholders and other syntactic elements)\r\n- Maybe generate an HTML or other directly-consumable version of it so you can read the docs offline instead of having to go through GitHub's repo viewer or an editor for the Markdown rendering? Could be a nicer reading experience overall. Markdown is a developer format, not a great format for readers.\r\n- Move subordinate content like inline images to a `resources` or `images` subdirectory, so only human-facing topic pages remain in the main directory.\r\n\r\nThoughts?\r\n\r\nA couple questions:\r\n\r\nDo we need to preserve the URLs for the `doc` pages as they're currently presented on GitHub? That is, is the URL `https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/C%2B%2B-Standard-Libraries.md` an official public point of access to this doco that we need to keep working even if we reorganize the doco? Or can we treat this as just part of the repo, and as long as the pages are navigable from wherever users find that `doc/README.md` then we're okay?\r\n\r\n(I hope the answer to that is \"no\"; having the GitHub web view of your main repo be a main public documentation site feels a little wonky to me. At the least we should be pushing it to GitHub Pages or something.)"},"comment":{"url":"https://api.github.com/repos/Homebrew/homebrew/issues/comments/168280598","html_url":"https://github.com/Homebrew/homebrew/issues/47164#issuecomment-168280598","issue_url":"https://api.github.com/repos/Homebrew/homebrew/issues/47164","id":168280598,"user":{"login":"zmwangx","id":4149852,"avatar_url":"https://avatars.githubusercontent.com/u/4149852?v=3","gravatar_id":"","url":"https://api.github.com/users/zmwangx","html_url":"https://github.com/zmwangx","followers_url":"https://api.github.com/users/zmwangx/followers","following_url":"https://api.github.com/users/zmwangx/following{/other_user}","gists_url":"https://api.github.com/users/zmwangx/gists{/gist_id}","starred_url":"https://api.github.com/users/zmwangx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zmwangx/subscriptions","organizations_url":"https://api.github.com/users/zmwangx/orgs","repos_url":"https://api.github.com/users/zmwangx/repos","events_url":"https://api.github.com/users/zmwangx/events{/privacy}","received_events_url":"https://api.github.com/users/zmwangx/received_events","type":"User","site_admin":false},"created_at":"2016-01-01T03:44:04Z","updated_at":"2016-01-01T03:44:04Z","body":"May I suggest that TOC also be added to individual pages, especially Formula Cookbook, which is a hell of a long document? With [`doctoc`](https://github.com/thlorenz/doctoc) it's just one single command away (be it initial generation or updates)."}}