<commit_before>---
layout: post
title: "Strange Alien Technology"
subtitle: "Helping New Collaborators Get Onboard"
date: 2015-05-17
permalink: ten-minute-plans
---

The thing that originally lead me to the open science movement is one of the things I remain most passionate about: code reuse. It drives me B-A-N-A-N-A-S when we start from scratch unnecessarily; code reuse is a big piece of what 'standing on the shoulders of giants' means today.

Discoverability is the first obvious barrier to reuse; but I'm betting that the stronger communication and community ties that undergird the [Study Group program][studyGroups] we're spooling up over at Mozilla will take the punch out of that one. We experience the next big hurdle every time we look at someone else's code for the first time, and ask ourselves, brow furrowed and slightly annoyed, *what is this hot mess, anyway?*

Making sense of someone else's code is harder than writing your own. Write your own, and you can use only tools and techniques you are comfortable with, in patterns that make intuitive sense to you, one step at a time. Use someone else's, and there's no telling what techno-alchemy they'll have pulled from the deep corners of their mind, too late at night and too close to their submission deadline, that you now have to contend with. 

For most, myself included for many years, that's game over - figuring out what code science hath wrought is just too big a barrier to feel worthwhile. How can we make this easier? Recently I've been exploring the possibility of building better on-ramps to coding projects, in the form of the Ten Minute Plan.

#### Ten Minute Plans

Nobody RTFMs - especially not me, probably because most docs rarely help me understand how a project is put together. What I'm starting to do and would like to see more of, is the creation of what I call 'ten minute plans' for coding project: a description that gives a newcomer a short, high-level tour of the programmatic logic of the project, that can be read and digested in under ten minutes.

A good ten minute plan should:

 - Give people an introduction to the qualitative logic of the program, so they can imagine its operation at high level.
 - Give people an overview of how all the technical pieces fit together (who calls who, and when?), possibly as a flow chart.
 - Point people at a handy cheat sheet for anything they're likely to need to refer to frequently during development (variable definitions, function specs).

A ten minute plan **does not**:

 - Include every detail about the operation and logic of the software.
 - Explore in full technical depth the details of even the parts of the code it does touch on.
 - Substitute for more complete or conventional forms of documentation. 

#### Sure buy why?

The point of the ten minute plan is to help new users and contributors build a first mental model of the code - there will still be tons of details left to learn after the fact, but at least they've got the general lay of the land. While we certainly can't communicate everything about a piece of code in ten minutes (and shouldn't try), the one crucial thing I think we can do, is dispel that overwhelming sense of 'WTF?' people experience when they first look at our code.<commit_msg>and collaboration, too!<commit_after>---
layout: post
title: "Strange Alien Technology"
subtitle: "Helping New Collaborators Get Onboard"
date: 2015-05-17
permalink: ten-minute-plans
---

The thing that originally lead me to the open science movement is one of the things I remain most passionate about: code reuse & collaboration. It drives me B-A-N-A-N-A-S when we start from scratch unnecessarily; code reuse is a big piece of what 'standing on the shoulders of giants' means today.

Discoverability is the first obvious barrier to finding opportunities to work together; but I'm betting that the stronger communication and community ties that undergird the [Study Group program][studyGroups] we're spooling up over at Mozilla will take the punch out of that one. We experience the next big hurdle every time we look at someone else's code for the first time, and ask ourselves, brow furrowed and slightly annoyed, *what is this hot mess, anyway?*

Making sense of someone else's code is harder than writing your own. Write your own, and you can use only tools and techniques you are comfortable with, in patterns that make intuitive sense to you, one step at a time. Use someone else's, and there's no telling what techno-alchemy they'll have pulled from the deep corners of their mind, too late at night and too close to their submission deadline, that you now have to contend with. 

For most, myself included for many years, that's game over - figuring out what code science hath wrought is just too big a barrier to feel worthwhile. How can we make this easier? Recently I've been exploring the possibility of building better on-ramps to coding projects, in the form of the Ten Minute Plan.

#### Ten Minute Plans

Nobody RTFMs - especially not me, probably because most docs rarely help me understand how a project is put together. What I'm starting to do and would like to see more of, is the creation of what I call 'ten minute plans' for coding project: a description that gives a newcomer a short, high-level tour of the programmatic logic of the project, that can be read and digested in under ten minutes.

A good ten minute plan should:

 - Give people an introduction to the qualitative logic of the program, so they can imagine its operation at high level.
 - Give people an overview of how all the technical pieces fit together (who calls who, and when?), possibly as a flow chart.
 - Point people at a handy cheat sheet for anything they're likely to need to refer to frequently during development (variable definitions, function specs).

A ten minute plan **does not**:

 - Include every detail about the operation and logic of the software.
 - Explore in full technical depth the details of even the parts of the code it does touch on.
 - Substitute for more complete or conventional forms of documentation. 

#### Sure buy why?

The point of the ten minute plan is to help new users and contributors build a first mental model of the code - there will still be tons of details left to learn after the fact, but at least they've got the general lay of the land. While we certainly can't communicate everything about a piece of code in ten minutes (and shouldn't try), the one crucial thing I think we can do, is dispel that overwhelming sense of 'WTF?' people experience when they first look at our code.
{'fraction_non_alphanumeric': 0.042014257545882, 'fraction_numerical': 0.0024268163203397543, 'mean_word_length': 4.254183266932271, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1054739', 'n_tokens_mistral': 1613, 'n_tokens_neox': 1501, 'n_words': 1098}