"Lab Manual"

[kousu]

As I recall it, redoing the website -- getting it off dokuwiki and making contributions a lot more accessible -- was inspired by this thread in March where @jcohenadad asked @neuropoly/consultants and @neuropoly/research-associates to review this other thread which opens

Russ Poldrack
@russpoldrack
Mar 25
I’d like to develop a public-facing Standard Operation Procedures page for our lab, outlining our default practices. Does anyone have good examples (from your own lab or others) that we might build off of?

4:04 PM · Mar 25, 2021

Now that the migration is settling down, we should all reflect what the purpose of the sites (both https://github.com/neuropoly/neuro.polymtl.ca and https://github.com/neuropoly/intranet.neuro.polymtl.ca) are.

I think we should be proud that the internal docs are now open source, not locked behind the old "internal resources" link, largely thanks to @ahill187's month+ porting and sorting through old data (thank you so much for grinding through that!). It means we've achieved this!:

has an easy to navigate, simple and nice interface. I'd advocate for rendering from GitHub via markdown for easy contribution.

I was enthusiastic about that and about all the thread's other examples that encourage open sourcing lab knowledge, not just in research processes but also in bureaucratic and cultural ones. Most people won't be interested, but for candidates considering joining us, other labs looking to compare or improve, or just ourselves, having a well-curated manual that's easy use from anywhere is very helpful. Holding ourselves to well-documented open source academics I hope will push us to take less shortcuts and make the processes themselves more rationalized and sustainable; and where they're not at least we have the institutional knowledge archived.

In this thread I would like us to:

• get (some) consensus on the rhetorical goal of the docs
• decide terminology: "site" vs "wiki", "intranet" vs "lab manual"
• decide if updates will be ad-hoc or scheduled as an annual lab-wide team project

Myself, I would propose:

• the purpose of the site is to be an reference point for ourselves and something we can share proudly with other labs as a standard worth copying
• emphasizing the public facing side and the internal facing side are really the same side, because we're working in an open style
  • and that's why we should Re-merging intranet.neuro.polymtl.ca <-> neuro.polymtl.ca neuro.polymtl.ca#30
• centralizing most "tips and tricks"-style documentation that's currently spread out across several project wikis (https://github.com/spinalcordtoolbox/spinalcordtoolbox/wiki, https://github.com/neuropoly/data-management/wiki, https://github.com/ivadomed/ivadomed/wiki, https://github.com/shimming-toolbox/shimming-toolbox/wiki)

[kousu]

Examples

(extracted from the Twitter thread)

• https://github.com/alylab/labmanual/blob/master/aly-lab-manual.pdf
• https://osf.io/mdh87/wiki/home/
• https://thebiologist.rsb.org.uk/biologist-features/how-to-write-a-lab-handbook
• http://handbook-public.themusiclab.org/
• https://psyarxiv.com/6jmhe / https://osf.io/q29nf/
• https://nrdg.github.io/sop/intro.html
• https://docs.google.com/document/d/1YaAoqtzC8H09reIt7cK1bNnAvZg7L-6O6BxMj-3jWpA/edit?usp=sharing
• https://alexandercoppock.com/Green-Lab-SOP/Green_Lab_SOP.pdf
• https://github.com/ContextLab/lab-manual
• https://mindalab.com/resources/ / https://osf.io/fztua/
• https://kobedesender.com/lab-philosophy/
• https://neurodata.io/about/agreements/
• https://github.com/WhitakerLab/Onboarding
• https://docs.google.com/document/d/1nP-5ZNCfHCgzU7X5XL1eVmOiP_Fr4r6qrcxPxpzAoTk/edit
• https://jupyterhub-team-compass.readthedocs.io/en/latest/
• http://www.sexchrlab.org/lab#/expectations
• https://faculty.newpaltz.edu/glenngeher/new-paltz-evolutionary-psychology-lab-member-orientation-page/
• https://tyelab.mit.edu/philosophy/b
• http://jpeelle.net/peellelab_manual.pdf (source code)
  • interestingly, mentions a separate wiki but does not link to it?
• https://ccmorey.github.io/labHandbook/
• https://docs.google.com/document/d/1phmA17c_hkAfLZN1yMXtFlCYlEqXEc8izEQsfoqgdTY/edit
• http://www.thememolab.org/research/
  • Like us, has an 'internal' link buried at the bottom of the page. Unlike us, it goes to https://sites.google.com/bc.edu/memolab/home which is 404'ing at the moment.

In the startup world, these company handbooks have been particularly influential for their radical openness:

• https://about.gitlab.com/handbook/
• https://basecamp.com/handbook
• https://archive.org/details/ValveEmployeeHandbook

Meta-manuals

• https://github.com/samuelmehr/labhandbooks / https://twitter.com/samuelmehr/status/1139733291899080705
  • is a suggested table of contents, feature-extracted from 25 existing open source lab manuals
• http://jonathanpeelle.net/blog/2016/01/07/maintaining-a-lab-manual

[joshuacwnewton]

get (some) consensus on the rhetorical goal of the docs

I'm a little confused about what this question is asking... 🤔

decide terminology: "site" vs "wiki", "intranet" vs "lab manual"

Personally, I prefer:

• Lab website ("Wiki" makes me think of an internal knowledge source, but neuro.polymtl.ca (to me) is first and foremost a landing page for people looking to learn more about the lab.)
• Lab manual. ("Intranet" to me feels like a functional term -- a set of pages that are only accessible via a specific internal network. Our lab manual is definitely not that, so the term always felt a bit misleading to me.)

decide if updates will be ad-hoc or scheduled as an annual lab-wide team project

Ad-hoc is the current approach, and I feel like it's worked... well enough so far?

Plus, I'm a bit hesitant about any big new scheduled efforts, considering how easy it is to propose, hype up, then eventually drop an idea. Coordination is difficult and labour-intensive! I'm skeptical about whether it would possible to rope the full lab into... working on internal docs? 😅

Myself, I would propose:

I don't really have any complaints about anything you've proposed. 🙂

[jcohenadad]

Lab website ("Wiki" makes me think of an internal knowledge source, but neuro.polymtl.ca (to me) is first and foremost a landing page for people looking to learn more about the lab.)

👍

Lab manual. ("Intranet" to me feels like a functional term -- a set of pages that are only accessible via a specific internal network. Our lab manual is definitely not that, so the term always felt a bit misleading to me.)

i don't have a strong feeling but the only thing in favor of the 'intranet' is that the URL says 'intranet.xxx'. But i guess that's not tooooo confusing...