Better project description on the readme page

[marc-vdm]

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]

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]

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]

old