search

python-streamz / streamz

Real-time stream processing for python
https://streamz.readthedocs.io/en/latest/
BSD 3-Clause "New" or "Revised" License
1.24k stars 149 forks source link

PROPOSAL: Update docs #359

Open chinmaychandak opened 4 years ago

chinmaychandak commented 4 years ago

I know we talked about updating the documentation so that it is more current and reads better (not that it doesn't read well now, but I feel certain API/aspects of the library can be put forward in a little cleaner fashion).

I suggest we also add some comments/TODOs in the codebase if possible so that it is more understandable to developers. But this is just my opinion.

Any suggestions on how we can start the process, and what all needs to be done?

I think it would also be immensely beneficial if we add tags to our issues — bugs, feature requests, proposals, maybe more. What do you guys think?

martindurant commented 4 years ago

I am, in general, in favour of all of your suggestions. However, each costs some effort. For example, issue tags are probably the lowest priority, since they need to be created and applied (unless we expect the issue posters to self-apply), and there are not enough people watching this repo to need to filter by tag.

I would certainly start with the documentation, and we could perhaps do this as a one-day sprint. The front page doesn't even mention "real-time", which I think really is the unique point (not the construction of process graphs, which can be done in lots of ways).

I am uncertain about code comments, since I'm not sure the kind of thing you have in mind. Things we really do mean to do might be better as issues - or just to be to-done.

chinmaychandak commented 4 years ago

since they need to be created and applied (unless we expect the issue posters to self-apply), and there are not enough people watching this repo to need to filter by tag.

Makes sense. How about we just show the categories to the user while they create an issue? That is, if they select the Bug category, the title of the issue will be prefixed by [BUG]. Similarly, [FEA] for feature request.

we could perhaps do this as a one-day sprint.

This sounds awesome!

The front page doesn't even mention "real-time", which I think really is the unique point

Dang! Yes, this is really something that should be mentioned.

I am uncertain about code comments, since I'm not sure the kind of thing you have in mind.

I think "comments" might not have been my best choice for the word. I meant, we should maybe add a one-line description to some parts of the code base which might be a little complicated to understand (like the SDF windowing stack call is really difficult to understand). I think this would be more like update doc strings.

chinmaychandak commented 3 years ago

There are also a lot of inactive or rather old (outdated with the new functionality added) issues, which would be good to close. Just another thing that could be a good to-do item.

martindurant commented 3 years ago

This is coming around for a one-year anniversary :| I am now putting some effort into this package, hope to spend time on docs too.