FIX/DOC: Documentation

Dear all. I feel over the next release cycle we should chose improving our documentation as a main goal. I know most of us including myself find it more rewarding to add new code. But we must bite that bullet, I feel. If we distribute efforts a bit and get well organized it might be less of a pain. And importantly, as a project, we’ll be making more progress if newcomers find it easy to get started.

This includes at least the following points:

• make more explicit that small examples are actually API examples and shall not be taken too literally (e.g. prevent users from adding random noise-arrays to threir data when doing using spatio-temporal clustering, etc.) #6694 adds a warning to the top of the examples gallery
• disseminate slide shows, screen casts
• send a user poll to the mailing list
• reorganize examples (e.g. order by intent and processing-step) #2101
• add real tutorials with stronger commitment to the wording / the recommendations #3101
• merge MNE manual with MNE-Python docs

Help users with pitfalls:

• Starting with Python (#3265): #6694 adds an updated “getting started with python” page.
• the use of Montage
• working with a template brain this exists now
• n_jobs=1 to save memory
• freesurfer + source space API, vertex indices, vertex numbers (#3465)
• morphing and missing vertices (#4034)
• basic Python issues (e.g., paths #2052)
• +/- in Evoked
• integrate IPython notebooks?
• coversion between float32 and float64 data on read/write (https://github.com/mne-tools/mne-python/issues/2720)

“Migrating to / working with” section:

• Xfit / Xplotter (@Eric89GXL)
• FieldTrip (#3362)
• EEGLAB (@jona-sassenhagen?): explaining the distinction in channel types etc.

Bug reports (from @dengemann):

Set up list of things to check + rule out before filing a bug report, inspired by https://github.com/mxcl/homebrew/wiki/Troubleshooting

Extended tutorials:

• epochs selection and event handling (see #1963)
• artefact removal These have been expanded / overhauled by @drammock
• group statistics (make explicit 2 (spatial / no spatial prior) X 2 (F/T-test) API, clarify TFCE (it’s not another test, but an enhancement method)), clarify that despite t-test inputs, spatio-temporal permutation clustering is not parametric and alos it does not give a multiple comparison corrected t-map, which means it’s not just a thresholding to a parametric stat. Also add recent insights on decoding stats. Discuss repeated measure designs and options (hierarchial subtraction with t-test, rANOVA, etc.)
• coreg (#3358)

Manual:

• time-frequency module: tfr functions vs. psd functions
• saving objects to disk (we discuss reading but not saving/writing …) many tutorials now include this
• transformations (#3465)
• decoding section explaining how the API follows the sklearn convention. Subsections for spatial pattern methods & time gen + time decoding

For devs:

• cookbook like this with common idioms, one liners

cc @teonlamont @christianbrodbeck @mainakjas @rgoj @dgwakeman @adykstra @legitta @deep-introspection @olaf @mshamalainen @mluessi @Eric89GXL @agramfort … and and and …

[choldgraf]

Cool - it’ll be roughly January 27th, planned to last about a week. We’ll probably have one joint meeting at the start to assign projects / get people up to speed (maybe have some tutorials and demos, etc), and then some short checkups throughout (or at the end of) the week. So plenty of time for independent working…

[larsoner]

Closing for #6794