search

NeurodataWithoutBorders / pynwb

A Python API for working with Neurodata stored in the NWB Format
https://pynwb.readthedocs.io
Other
173 stars 82 forks source link

Software Architecture #649

Open ukos-git opened 5 years ago

ukos-git commented 5 years ago

pynwb really gave me a hard time getting to know the class interactions.

I think a graph which shows the dependencies for write/read interactions with the main classes and subclasses as well as thier interfaces would be highly needed.

If you can do that in a finite and small amount of time. Go for it!

Originally posted by @t-b in https://github.com/NeurodataWithoutBorders/pynwb/pull/641#issuecomment-427126050

But I don't think, I can do this alone because I'm new to pynwb, do not fully see all the interfaces and it will probably not be correct having limited time. So this graph is open for collaboration.

The goal is a proper documentation of the involved functions and classes in read/write operations. Nevertheless, it is only a rough sketch by now.

https://sketchboard.me/FBfL0rh6ymSJ#/

ajtritt commented 5 years ago

Have you looked at this?

https://pynwb.readthedocs.io/en/latest/overview_software_architecture.html

ukos-git commented 5 years ago

I understand that it is hard to see any difference, but I was interested in the interfaces that connect the classes. There is no graph for this in the software architecture section. I wanted to have a base to talk about introduced changes in my PR https://github.com/NeurodataWithoutBorders/pynwb/pull/641

Other than that, the graphs are not built in an updatable manner. They seem a bit lost and do not fit in. Probably they are built for a poster presentation and then added to the sphinx docu. The software architecture section itself is not the best when it comes to understandability. It definitely needs a top-to-bottom rework but there are probably thing that are more important.

oruebel commented 5 years ago

@ukos-git the PowerPoint files with the current figures are in the folder docs/source/figures. I agree that PowerPoint is not an ideal process but we simply have not had the chance yet to translate the figures into other tools, but at least it gives you editable sources to start from.

Writing documentation is a hard and tedious task. We are doing the best we can given the limited resources we have. Any help to improve the documentation is more than welcome. I appreciate your help in making PyNWB easier to learn 👍 . Ultimately, it is users like you that are learning the software that can most easily identify where information is missing.

On a separate note, collaborative software development is hard and ultimately we are a community with a common goal. In that regard, I would like us to be all mindful and positive when we discuss issues (in particular when we work in a public forum like GitHub). In this case, I'm sure your intend in this issue is entirely positive and trying to help us make PyNWB better 👍. So instead of criticizing what is there ("pynwb really gave me a hard time getting to know ..." ) it would be better to focus on how to make things better by describing 1) the use case you are trying to achieve (I'm trying to learn the interfaces that connect the classes) and 2) the solution (it would be helpful to extend the existing documentation on the software architecture to describe how the interfaces connect with each other on read/write.

Thanks for your sketch. I won't have the time to work on this today but I'll take a look to see what we can do.