making it easier for people to contribute via documentation and todo in code

[coolharsh55]

It can be difficult to dive in and start developing a feature by oneself. Instead, we can put in comments indicating places of interest where people can add functionality or improve existing features. Something like this:

def foo(*args, **kwargs):
    # does things x, y, and z
    # ...
    # todo: add assertions for arguments
    return x, y, z

This will allow a general search for todo in github to show places of interest where everybody can contribute to. Things like assertions, validations, refactoring, enhancements, and other things major and minor can be added in code via helpful comments. This way, everything does not need to be attached to an issue, only things that require discussions or are major features, or require management can be managed by issues. Using todo in documentation will also encourage people to peep into the code rather than just talk over slack or dig through the issues.

[Heasummn]

I think we should use a documentation generator. I loved the concept of JavaDocs in Java. Sphinx would be my choice for something of this in Python.

[SanketDG]

@Heasummn I think mkdocs makes more sense here. Sphinx is not easy to get started with IMHO.

[Heasummn]

@SanketDG You're right, mkdocs seems much simpler, though I've done Sphinx before and that causes bias in me.

[nitinpaultifr]

Documentation apart, I like the idea of adding 'TODOs' in the code so that people can look them up and do simple stuff, instead of tackling issues and bugs if they don't want to

[SanketDG]

I have been thinking and I dont think a separate documentation would be needed. We have the wiki, which frankly is hidden, so we need it linked in the right places.

And then, with the combination of docstrings and inline comments, docs seem redundant.

Do we still need one @Heasummn @npaul2811 @coolharsh55 ?