Documentation improvements

[choldgraf]

Here I'm going to list some of the topics that people have mentioned below, as well as some that I've noticed myself. This pulls in outstanding (aka, unchecked) points within #3082 as well.

link to the dev docs here
link to docs mega-issue here
maybe we wanna merge this thread in with the other mega-doc issue, but for now I'll work from here unless folks say otherwise. I think there's value in not having that issue get too gigantic.

General

• Make it more clear the difference between manual and the tutorials. What is the conceptual difference between, e.g. this manual item and this tutorail item
• The dev docs are still matplotlib 1.X, will they be ported to 2.X at some point? The plots look prettier there :)
• The CSS of the website causes it to fill the width of the screen at all times. For some things (e.g. the tutorials / examples) I feel like it might be easier to read the material if the CSS stuck with a particular width (e.g. the width of jupyter notebooks)

Little things

• the RSA example doesn't seem to be running
• this durface decimation example isn't plotting anything because all the mayavi lines are commented out example no longer exists
• the event reading example doesn't have a plot, but we could easily use the plot_events function.
• the description in this example references a python file, but instead should link to the example for this file in the gallery. realtime is its own module now
• the report example could show a sample image of what a report looks like.
• The clickable image example could show or reference the 3-D snapshotting functionality demoed here example no longer exists
• Clarify that it's important to baseline epochs before computing noise covariance in one of the examples or in the manual done in auto_tutorials/source-modeling/plot_compute_covariance.html
• Elaborate on use of the lambda2 parameter in apply_inverse. E.g., why is it set to 1/2**3 most of the time? this is now tolerably well explained in the inverse modeling section of the overview tutorial. Though it doesn't say why we assume SNR of 3; at least it explains what lambda2 represents and users can infer how to sensibly tweak it.

Medium things

• create a workflow diagram for a processing pipeline (see DOC: Updating the MNE workflow image? #3669 for example)
• Add an example of how to grand average source data. (there seems to be a function for evoked and TF data but not for source). Maybe by morphing them creating a multidimensional matrix np.array and doing the average manually.
• Improve documentation about signal-to-noise estimation, see ENH: improve doc for SNR estimate #1857
• A better tutorial for make_bem_watershed. And what to do with the error that one surface intersects with another. (sort of a freesurfer problem)
• Add a tutorial for Granger analysis using nipy (ENH: granger #3548)
• Add a tutorial on co-registration (ENH: Tutorial on coreg #3358)
• Document risks of whitening with multiple SSS runs (FIX: whitening issue when combining runs #1902)

Large things

• Documenting the connectivity module (DOC: connectivity module #2847)

[kingjr]

I think we should merge the 'manual' and the 'tutorials'.

[larsoner]

Good targets would be:

• @choldgraf and @kingjr ideas for updating the workflow, especially if someone wants to make a client-side rendered workflow image :)
• @teonbrooks small issues you hit
• @dengemann SNR doc
• @dengemann connectivity doc
• and there is of course the doc mega-issue
• @kingjr granger tutorial
• @christianbrodbeck tutorial on coreg

[larsoner]

And:

• @christianbrodbeck tutorial on coreg: ENH: Tutorial on coreg #3358

[choldgraf]

@Eric89GXL it seems like most of those links just redirect back to this issue?

Those are great suggestions though. If we can get an idea for prioritizing these in some way that would be really helpful (e.g. I think a tutorial on coregistration would be useful, especially if there could eventually be support for doing ecog coregistration using a CT scan or something)

I can spend some time working on things, and at the least am going to be around to discuss / look over PRs / etc for the week

[claire-braboszcz]

I've seen on Project that @kingjr was thinking of writing a tutorial on time-frequency decoding. I'd be very interested in such a tutorial that would complement nicely the current documentation.

[larsoner]

@choldgraf fixed all the links.

Are people working on any of these this week?

[choldgraf]

I'm gonna take a pass through this and try to organize a little bit today...just been slow on doing it since I had to get the docathon up and running first :) I think @teonbrooks is going to help out as well

[choldgraf]

I'm looking through some of these issues etc now, and it's a little unclear to me what is the difference between "tutorials" and the "guide". Can somebody give me the high-level view of why these are two different things? Is the guide meant to be comprehensive and very MNE-specific, whereas tutorials are more conceptual in nature?

[choldgraf]

E.g., what would be the difference between this page:

http://martinos.org/mne/stable/manual/time_frequency.html

and this page:

http://martinos.org/mne/stable/auto_tutorials/plot_sensors_time_frequency.html

[agramfort]

hum... maybe http://martinos.org/mne/stable/manual/time_frequency.html should not be there. the "idea" is to have the manual more conceptual closer to the explanation of the method in a book or paper and to say when you should or should not use it. But maybe it's too ambitious... the tutorial are more really how to do things with MNE. most of the manual content comes from the pdf doc of the MNE-C code.

[choldgraf]

Maybe it'd be worth having language on the landing page that describes this? I remember when I was starting with MNE it was unclear which of the two I should be reading. I actually really like the idea of having more high-level concepts-based materials in the repo, since a lot of students learn by looking through project docs these days.

I think a challenge is that we'd need to be fairly vigilant about what belongs in tutorials vs. manual. For example, in tutorials there is this general example on filtering. If the manual is supposed to be more "concepts based" then this should really be in there. My assumption is that most users will get a feeling for what a section of the website covers by clicking a random link and seeing what kind of information is in there.

[choldgraf]

And for a converse example, this manual page on epochs etc feels much more like a "how to use MNE" kind of document than a "general concepts" kind of document.

Maybe worth spending an hour at the meeting in NYC to chat about best way to organize / present this information? I think there's a lot of great info in there - wanna make sure that people will find it!

[kingjr]

+1

…

On Saturday, 11 March 2017, Chris Holdgraf ***@***.***> wrote: And for a converse example, this manual page on epochs etc <http://martinos.org/mne/stable/manual/cookbook.html#epoching-and-evoked-data> feels much more like a "how to use MNE" kind of document than a "general concepts" kind of document. Maybe worth spending an hour at the meeting in NYC to chat about best way to organize / present this information? I think there's a lot of great info in there - wanna make sure that people will find it! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3985 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEp7DBP3AdHpmpGRM16LAh8YuouNdqmPks5rktTXgaJpZM4L_jte> .

[agramfort]

+ np.info['int64'].max Alex

[choldgraf]

sounds like all(opinion > 0 for opinion in thread_opinions) == True

I'll add to the project board

[prateekj117]

@larsoner We should change the installation command for sphinx-autobuild and doc8 in the documentation from conda install sphinx-autobuild doc8 to conda install -c conda-forge sphinx-autobuild doc8 in case someone does not have conda-forge added to their channel list.

Rather than opening a separate issue, I think it would be more appropriate to add it here.

[drammock]

@prateekj117 thanks for pointing that out, see #7050

[drammock]

All of the remaining unchecked boxes in this todo-list have been added to #6794. Closing.

[choldgraf]

amazing!