Better documentation and educational components

[satra]

• Clean up documentation for users and developers
• Merge tutorials with education in mind
• Separate examples into teaching examples and research-useful examples
• Allow for users to quickly edit documentation without going through full pull-requests

[miykael]

Hi @satra and all. Congratulation on the Nipype grant, that's amazing news!!!
Concerning the better documentation and the educational component. I'm very happy to help with this issue. Would there be any interest of incorporating the current beginner's guide into the main homepage. I'm aware that this might not be desired, as the beginner's guide has it's own "style" and might be too far from what you actually imagined. But I'm happy to morph it into whatever is needed to solve this issue.

[satra]

@miykael - what i would like to see is a set of jupyter notebooks that are fully executable and also turn into reasonable slideshows. this will take some effort to implement, but i would like to see small chunks build through different components of nipype.

as a related example see:

http://mbakker7.github.io/exploratory_computing_with_python/

[mwaskom]

Feel free to fork https://github.com/mwaskom/nipype_concepts :)

[satra]

@mwaskom - indeed. we really need to start putting all these pieces together. what i like about mark's work are study examples that he created which makes people implement things. and i think his intro to python also can be re-formulated for biomedical scientists. ideally we will create a set of documents and tools that will work as a complete teaching package that we can use in our workshops as well.

i better finish the engine rewrite soon, so that we don't have to perform too many modifications! :)

[oesteban]

@satra In Udacity they are doing a course on tensorflow, check out the materials: https://github.com/tensorflow/tensorflow/blob/master/tensorflow/examples/udacity/README.md

I find particularly convenient the docker image, that you run and launches a jupyter server with the assignments. It takes around 2 minutes to get it started if you manage to install docker.

[fliem]

I'd be happy to work on educational notebooks as well.
I have put together some very basic ones for a tutorial (https://github.com/fliem/nipype_tutorial)
Just let me know what to do.

[satra]

@fliem - that's a great start.

here are some thoughts:

1. take the nipype tutorials that currently exist, extract concepts out of them and turn them into notebooks. we are happy to provide guidance and review things
2. perhaps setup something with mybinder.org for people to launch these notebooks and play around with them
3. ensure concepts cover mechanisms like hashing and provenance and debugging when things go wrong.

most people can setup nipype workflows quite easily following some basic instructions, the harder part is to debug execution errors, so if we can guide people through errors and how to fix them that would be very helpful.

we should also have sections on how to build your own interface and contribute code to nipype.

[fliem]

sounds good.
@satra @miykael how about doing this as a Brainhack Lausanne project? Are you going to attend?

[satra]

@fliem - i will be at brainhack in lausanne and this would be a good project there.

[miykael]

Hi @satra and @fliem. Sorry for the late reply, I was out of office for 2 weeks. Thanks @satra for the input, I'm particularly interested in mybinder.org.
I will also be at the Brainhack in Lausanne and I'm very happy to work on this project.

[djarecka]

@satra can we close this issue and open a new one if needed? I think missing part is at least partially covered in the issue from nipype_tutorial miykael/nipype_tutorial#37