Overhauled readme - Githubissues

py-why / dowhy

DoWhy is a Python library for causal inference that supports explicit modeling and testing of causal assumptions. DoWhy is based on a unified language for causal inference, combining causal graphical models and potential outcomes frameworks.

https://www.pywhy.org/dowhy

MIT License

6.89k stars 916 forks source link

Overhauled readme #1088

Closed bloebp closed 7 months ago

bloebp commented 7 months ago

The current readme is too overloaded for users. Changes here are:

Reduce it only the essential points, since most of the content is part of the documentation
Add image as overview of the offered features
Made connection between GCM and PO framework more consistent
Revise the GCM example to an executable code snipped
Extended some references to include GCM related work
Fix build status icon
Changed github references to py-why (was still pointing to microsoft)

Here the new readme: https://github.com/py-why/dowhy/blob/c0ac8433625b5693175629076ad32a92b0d1eb71/README.rst

The image in the key features section is not show. It is the following:

emrekiciman commented 7 months ago

Thanks for this, @bloebp ! The new README is much more streamlined and easier to read. A couple comments:

I'd highlight the "documentation is available" link at the top of the README much more strongly. Maybe put it in a highlighted box or a larger font. Also change to "documentation, user guide, and sample notebooks" to make it clear it is more than API docs.
Somewhere, we should mention that DoWhy is part of PyWhy and a family of tools, and point to https://pywhy.org/
I agree with Amit about the 'optional' language for refutations.
I'd suggest titling the whole "installation" and "example usage" together as a "Quick Start" guide. So the whole README becomes 3 major sections: (1) "Intro & key features"; (2) Quick Start; and (3) More information and resources. Not necessarily in this order.

bloebp commented 7 months ago

Thanks a lot @amit-sharma @emrekiciman!

Somehow, the options in displaying stuff in the README.rst is quite limited (and different from the usual rst files). I hope the new version now this is good compromise to make the documentation link more prominent.

The .rst file can be accessed here: https://github.com/py-why/dowhy/blob/c0ac8433625b5693175629076ad32a92b0d1eb71/README.rst

and the new image is:

PS: The reason why I didn't use the backdoor formula for identification is to avoid the impression that the other features are not relying on that.

Let me know what you think