Improve taxcalc documentation for contributors

[zrisher]

This issue is opened as a continuation of the discussion on our documentation needs started on issue #724, replicated below:

@martinholmer said:

How about adding to the release change log as we go? See issue #841.

@MattHJensen said:

Where do you think it would make sense to document this procedure for other contributors?

@martinholmer said:

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.

@MattHJensen said:

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:

1. Do a better job of manually pointing people to the content.
2. Make links to the content more visible.
3. Put the content in a new place (GH wiki or similar).

None of these feels like a golden bullet, though. Any other ideas?

@feenberg said:

The documentation needs a web page, github won't do. In fact, the project needs a couple of web pages and should not depend on github for anything other than source code control and ticketing. It isn't a good interface for users of the software to learn about it.

@MattHJensen said:

What do you see as the high priorities as far as content go?

@zrisher said:

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?

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.

@feenberg said:

Personally, I find github very off-putting and not something that economsits or policy types will be familiar with, or want to learn about. In practice, they may think "Oh, this sofrware is still in early stages of development - maybe I'll come back when they are far enough along to have a web page."

It is one thing to go to github to download a .tar.gz of a binary - but Github is not a way to "market" a new and complicated package to a possibly skeptical audience. A website doesn't need to be fancy, but it needs links to documentation that lead to online html, not a zip file.

[zrisher]

Personally, I find github very off-putting and not something that economsits or policy types will be familiar with, or want to learn about. In practice, they may think "Oh, this sofrware is still in early stages of development - maybe I'll come back when they are far enough along to have a web page."

@feenberg Ok, this makes sense! I see two very different consumers of documentation (/users) then:

1. economists / policy analysts - people who are primarily familiar with tax policy and analysis
2. programmers - people who are primarily familiar with coding.

For 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?

For 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.

I 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.

@MattHJensen @martinholmer @talumbau

[feenberg]

I think we need to decide who our pioneer users will be. Are they the tax policy crowd, who will use TB for what it already does, and then later recruit CS types to enhance it, or do we mean to find our initial users among programmers who will then show the package to their employers? I think the answer is obvious - tax policy first, then depend upon them to engage the programmers.

The TP folk will not find Github engaging. If I go to Github and search for taxbrain the first page I see is:

https://github.com/search?utf8=%E2%9C%93&q=taxbrain

There is a link to TaxBrain. That takes me to:

https://github.com/OpenSourcePolicyCenter/webapp-public

Is that a way to market a program to an economist? I recall being laughed at for saying that the undecorated TB website prototype was fine for release. It was a lot more friendly than this. But suppose I persist and select "docs" from this page. That takes me here:

https://github.com/OpenSourcePolicyCenter/webapp-public/tree/master/Docs

There is one link on that page, which takes me here:

https://github.com/OpenSourcePolicyCenter/webapp-public/blob/master/Docs/taxbrain_inputs_layout.xlsx

Which is completely empty aside from Github boilerplate.

Dan

[zrisher]

@MattHJensen Can I close this in favor of https://github.com/OpenSourcePolicyCenter/webapp-public/issues/318?

[MattHJensen]

@zrisher, I just left this open for a discussion of the original problem that was raised by @martinholmer, which is about Tax-Calculator documentation for contributors, not TaxBrain documentation for policy users. In particular, I had asked where he recommended that we put the change log procedures and he lamented that not everyone reads our contributor guide.

@MattHJensen said:

Where do you think it would make sense to document this procedure for other contributors?

@martinholmer said:

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.

@MattHJensen said:

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:

1. Do a better job of manually pointing people to the content.
2. Make links to the content more visible.
3. Put the content in a new place (GH wiki or similar).

None of these feels like a golden bullet, though. Any other ideas?

Perhaps this deserves a new issue, though.

[martinholmer]

There has been no discussion over the past seven months of issue #891, Improve taxcalc documentation for contributors. Documentation can always be improved, so I'm not saying this issue is resolved. However, it seems like any high priority aspects of this general topic deserve their own new issues, as @MattHJensen suggested seven months ago. Can #891 be closed?

@feenberg @zrisher

[MattHJensen]

Closing.