Improving onboarding and enabling contributions

[eriknw]

It will be an ongoing effort to make it easier to contribute to graphblas-algorithms, so lets gather ideas and prioritize in this thread. Heh, right now, I encourage potential contributors to be very patient. Things will get better/easier, I promise!

• Improve the overall documentation of python-graphblas
  • Also, point to "best" resources for Python users to learn GraphBLAS in general (i.e., choose a couple from https://graphblas.org/GraphBLAS-Pointers/)
• Add contributing documentation to python-graphblas and graphblas-algorithms
  • How to set up local dev environment, etc. Should borrow liberally from contributing docs from other libraries.
• Create issues for "starter algorithms"
  • Identify a networkx algorithm to implement
  • Link to existing GraphBLAS implementations (and papers, etc) if possible
  • Perhaps sketch an implementation in python-graphblas, but maybe not one that is fully tested or complete
    • Even with this, there is still plenty of work needed to add an algorithm
  • This may be an effective use of my (@eriknw) or @jim22k's time
  • See https://github.com/python-graphblas/graphblas-algorithms/wiki/Where-to-find-algorithms
• Create "algorithm template" notebook that helps guide development
  • Create example data, load datasets, guidelines for benchmarking, run networkx tests, etc.
• Create notebooks with exercises as e.g. self-guided tutorials
  • Example starter exercises:
    • Find neighbors of node X
    • Find "friends of friends"
    • Find predecessors (or successors) of directed graphs
    • etc.; there are lots of "simple" algorithms we can build up to
  • I think some notebooks should encourage hands-on experimentation, not just reading
• I think dev notebooks could be a nice side-effect of adding algorithms
  • For example, for triangle counting, there were lots of possibilities to choose from, and I decided based on benchmarks
  • These notebooks can help demonstrate how algorithm development is done, and help revise algorithms later if necessary
  • These may be messy. Not intended as tutorial notebooks. I have some notebooks around that probably belong somewhere.
  • I don't want to require a notebook for each algorithm, but it's a nice-to-have.
• Don't forget about contributions other than algorithms!

I'm the most familiar with both python-graphblas and graphblas-algorithms, so I trust my judgement the least regarding how to improve onboarding and enabling contributions. @MridulS, @z3y50n, @ParticularMiner, what do you think would be the most helpful? Also, thanks for your patience :)

[z3y50n]

These are all good points for a nicer, smoother onboarding process and making usage of graphblas much easier.

Personally, I feel we need to prioritize having a good reference documentation. This will at least give everyone the basic usage of graphblas' functions.

Besides that, a small tutorial like that of NetworkX could be helpful for a hands on example and exposure to graphblas.

[eriknw]

I agree with those priorities @z3y50n, thanks for the input.

Check out the documentation that @jim22k just created:
https://python-graphblas.readthedocs.io/en/latest/

I expect documentation will be an ongoing effort, so feedback is most welcome.