{"action":"created","issue":{"url":"https://api.github.com/repos/open-source-economics/Tax-Calculator/issues/891","repository_url":"https://api.github.com/repos/open-source-economics/Tax-Calculator","labels_url":"https://api.github.com/repos/open-source-economics/Tax-Calculator/issues/891/labels{/name}","comments_url":"https://api.github.com/repos/open-source-economics/Tax-Calculator/issues/891/comments","events_url":"https://api.github.com/repos/open-source-economics/Tax-Calculator/issues/891/events","html_url":"https://github.com/open-source-economics/Tax-Calculator/issues/891","id":174431597,"number":891,"title":"Documentation needs reorg","user":{"login":"zrisher","id":1958130,"avatar_url":"https://avatars.githubusercontent.com/u/1958130?v=3","gravatar_id":"","url":"https://api.github.com/users/zrisher","html_url":"https://github.com/zrisher","followers_url":"https://api.github.com/users/zrisher/followers","following_url":"https://api.github.com/users/zrisher/following{/other_user}","gists_url":"https://api.github.com/users/zrisher/gists{/gist_id}","starred_url":"https://api.github.com/users/zrisher/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zrisher/subscriptions","organizations_url":"https://api.github.com/users/zrisher/orgs","repos_url":"https://api.github.com/users/zrisher/repos","events_url":"https://api.github.com/users/zrisher/events{/privacy}","received_events_url":"https://api.github.com/users/zrisher/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":1,"created_at":"2016-09-01T03:59:32Z","updated_at":"2016-09-01T04:01:03Z","closed_at":null,"body":"This issue is opened as a continuation of the discussion on our documentation needs started on issue #724, replicated below:\r\n\r\n@martinholmer said:\r\n> How about adding to the release change log as we go? See issue #841.\r\n\r\n@MattHJensen said:\r\n> Where do you think it would make sense to document this procedure for other contributors?\r\n\r\n@martinholmer said:\r\n> Well, a few months ago I would have said the Contributor Guide, but now I'm not so sure. There isn't much evidence that new users are reading it. See, for example, open pull request #824 submitted by codykallen. First of all, this person is not even a GitHub user --- at least, that name does not come up when I type @cod. And, he doesn't seem to have read the Tax-Calculator README.md file, which says to read the Contributor Guide and to read the TESTING.md documents. So, I'm not sure investing a lot more time in these documents will make much difference.\r\n\r\n@MattHJensen said:\r\n> The content in these documents have been very helpful for new contributors and TC users in the past, but I have the same sense as you that people aren't finding it by themselves. If we agree that the content in these docs is helpful and that there is, in fact, even more content we want contributors to see, then I see three options:\r\n\r\n> 1. Do a better job of manually pointing people to the content.\r\n2. Make links to the content more visible.\r\n3. Put the content in a new place (GH wiki or similar).\r\n\r\n> None of these feels like a golden bullet, though. Any other ideas?\r\n\r\n@feenberg said:\r\n\r\n> The documentation needs a web page, github won't do. In fact, the project\r\nneeds a couple of web pages and should not depend on github for anything\r\nother than source code control and ticketing. It isn't a good interface\r\nfor users of the software to learn about it.\r\n\r\n@MattHJensen said:\r\n\r\n> What do you see as the high priorities as far as content go?\r\n\r\n@zrisher said:\r\n\r\n> I actually disagree, github was designed to facilitate easy contribution by people unfamiliar with a software project (just look at their About page). Github provides web pages, and offhand I can't think of any cases where a fully customizable web page provides significant advantages over writing your documentation in markdown or using a repo's wiki. Perhaps we can think of some ways in which our own web pages would provide superior documentation support?\r\n\r\n> I've used it for a long time, so I'm probably biased by familiarity. But I do think that indicates an advantage - anyone used to contributing to projects on Github will find it easy to navigate the documentation of any other repo.\r\n\r\n@feenberg said:\r\n\r\n> Personally, I find github very off-putting and not something that\r\neconomsits or policy types will be familiar with, or want to learn about.\r\nIn practice, they may think \"Oh, this sofrware is still in early stages of\r\ndevelopment - maybe I'll come back when they are far enough along to have\r\na web page.\"\r\n\r\n> It is one thing to go to github to download a .tar.gz of a binary - but\r\nGithub is not a way to \"market\" a new and complicated package to a\r\npossibly skeptical audience. A website doesn't need to be fancy, but it\r\nneeds links to documentation that lead to online html, not a zip file."},"comment":{"url":"https://api.github.com/repos/open-source-economics/Tax-Calculator/issues/comments/243970062","html_url":"https://github.com/open-source-economics/Tax-Calculator/issues/891#issuecomment-243970062","issue_url":"https://api.github.com/repos/open-source-economics/Tax-Calculator/issues/891","id":243970062,"user":{"login":"zrisher","id":1958130,"avatar_url":"https://avatars.githubusercontent.com/u/1958130?v=3","gravatar_id":"","url":"https://api.github.com/users/zrisher","html_url":"https://github.com/zrisher","followers_url":"https://api.github.com/users/zrisher/followers","following_url":"https://api.github.com/users/zrisher/following{/other_user}","gists_url":"https://api.github.com/users/zrisher/gists{/gist_id}","starred_url":"https://api.github.com/users/zrisher/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zrisher/subscriptions","organizations_url":"https://api.github.com/users/zrisher/orgs","repos_url":"https://api.github.com/users/zrisher/repos","events_url":"https://api.github.com/users/zrisher/events{/privacy}","received_events_url":"https://api.github.com/users/zrisher/received_events","type":"User","site_admin":false},"created_at":"2016-09-01T04:01:03Z","updated_at":"2016-09-01T04:01:03Z","body":"> Personally, I find github very off-putting and not something that\r\neconomsits or policy types will be familiar with, or want to learn about.\r\nIn practice, they may think \"Oh, this sofrware is still in early stages of\r\ndevelopment - maybe I'll come back when they are far enough along to have\r\na web page.\"\r\n\r\n@feenberg Ok, this makes sense! I see two very different consumers of documentation (/users) then: \r\n\r\n1. economists / policy analysts - people who are primarily familiar with tax policy and analysis \r\n2. programmers - people who are primarily familiar with coding. \r\n\r\nFor group 1, we need a website geared primarily towards selling them on the project and making it easy to apply to their work. Perhaps we could adapt webapp-public to provide this?\r\n\r\nFor group 2, we (in my opinion) should make the github pages as accessible and organized as possible so they can quickly dive into the code in a familiar environment.\r\n\r\nI think this approach would allow us to provide a tailored experience to each group and maximize their willingness to work with and contribute to the project.\r\n\r\n@MattHJensen @martinholmer @talumbau"}}
{"actor":{"display_login":"zrisher"}}