Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better project description on the readme page #346

Closed
marc-vdm opened this issue Dec 16, 2019 · 3 comments
Closed

Better project description on the readme page #346

marc-vdm opened this issue Dec 16, 2019 · 3 comments
Labels
documentation PRs that refer to documentation at any level (code, readthedocs, etc.) feature Issues/PRs related to a new feature

Comments

@marc-vdm
Copy link
Member

Some time ago, I ran into this reddit post commenting on how (open source) projects could really benefit from better descriptions of what they do and why. I think we can also learn from this thread, and especially the comment referring to this checklist.

Would it be an idea to work on this? I think we can draw some useful text from the paper recently added to the readme and refer to that for further reading.

Thoughts?

@dgdekoning dgdekoning added documentation PRs that refer to documentation at any level (code, readthedocs, etc.) feature Issues/PRs related to a new feature labels Dec 16, 2019
@dgdekoning
Copy link
Contributor

dgdekoning commented Dec 16, 2019

I definitely agree with higher quality documentation. Its been brought up a few times in different forms (adding a wiki, using sphinx to construct a readthedocs page from docstrings, see #153, #158 and #167).

Personally, I would love to put more time into this, but it usually comes down to a list of other things that also have to be done and documentation almost always comes last (usually with the reasoning 'it'll be easier to do all at once after these new features have been added...').

If you give me some time I can go through the sources you found and see which parts would improve the readme / overal documentation for this project. Of course, if you have suggestions for improvements we welcome pull-requests :).

@marc-vdm
Copy link
Member Author

I think we can divide the larger conversation into two parts, one is the documentation for AB developers, the other is documentation for users (that might not be familiar with coding and asking for help on github).

Would it be an idea to set up a requirement for PRs to include Sphinx compatible descriptions for whatever section (class or function) of code they worked on? This would at least solve part of the problem for new/changing code, we can then never do the old code do the old code when there is time/money/motivation.

For the other problem (documentation for users), I`d be happy to try to improve the readme, but perhaps you or @bsteubing would be better able to explain the why of the AB.

@marc-vdm
Copy link
Member Author

old

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation PRs that refer to documentation at any level (code, readthedocs, etc.) feature Issues/PRs related to a new feature
Projects
None yet
Development

No branches or pull requests

2 participants