In our continuing shift towards using the new Q&A feature and the new Activity grids as a framework for collaboration on PublicLab.org, we're encouraging people to post their work more in the spirit of Instructables.com -- "showing each other how to do something" rather than just telling people about something you've done. This shifts the emphasis from solely documenting what you've done, to helping others do it too. (image above from a Lego Technics kit)
There are several reasons we like this. A how-to guide (what we're calling Activities) must have extremely thorough and easy-to-follow steps (and may need to be revised if people get stuck). Perhaps even more importantly, its success (we hope) can be measured by how many people are able to follow the steps successfully, which exercises and fuels the power of broad communities and open science.
What's needed?
While there are various types of activities for various purposes, all of them ought to set out some basic information to help people get started:
- a description of the purpose of the activity
- a list of materials needed
- a clear description of your conditions (e.g. lighting, temperature, or other relevant factors)
- a detailed sequence of steps to follow
- a description of how to confirm you've followed the steps correctly
- a hypothesis or expected outcome
- a discussion of your results
- a list of questions to explore next (unknowns, or followup activities)
- a request for input (there's always room for improvement!)
Speaking of room for improvement, can folks suggest other important parts of an activity? With an eye toward making it easy for anyone to write and post activities, and for others to replicate them, what's the minimum necessary?
(IKEA Stonehenge. Justin Pollard, John Lloyd, and Stevyn Colgan designed an IKEA manual for Stonehenge, publishing it under the title HËNJ in the QI 'H' Annual)
Drafts welcome
We'd also like to suggest that people post things early -- to share ideas, solicit input, and acknowledge that most posted activities will go through some (if not many) revisions as people try them out and offer feedback. Could we even have a separate "Publish Draft" button so they're clearly marked as such, and people know they're encouraged to share early and often?
Break it up!
One important way we think will increase the chances that people will complete a replication of your activity is to simply write shorter activities -- perhaps breaking up a longer set of steps into several related modules. Instead of posting a long and complex activity, a few shorter ones -- each with a simple way to verify that the steps so far were correctly completed -- are much more accessible, and will tend to separate distinct possible causes of failure for easier troubleshooting.
Distinct modular activities can be linked and referenced to create a larger activity that might span, for example, building and verifying a tool functions properly, tool calibration, and lab or field tests of various materials using the tool. Even if the final activity cannot be completed without the previous activities first, breaking them out into distinct activities that build on each other will help the onboarding process.
(above, @cfastie shows how to swap a lens in a #mobius camera)
Supporting activity authors
Finally, beyond this overview, what more can we do to make it easy to write good activities? Some have suggested a kind of "assistance group" who could provide helpful tips and constructive critique to people posting on Public Lab. This sounds like a great idea, and potentially extra helpful to folks who are hesitant or unsure of what makes a good and thorough post.
Would "activity templates" be useful, to the extent that they can be generalized?
We're also, of course, posting some example Activities, such as this spectrometer calibration activity, which we hope will help set some conventions.
Next steps
We're also interested in how people could be introduced to other activities on a topic once they complete the current one -- maybe there's a "sequence" of activities that grow in complexity? Or we could display a mini activity grid of "related activities" at the bottom of each one?
Finally, we're trying to figure out how people can request an activity for something they want to learn to do, but for which there is not yet an activity posted. This'll be especially important as we're starting out, since we have very few complete activities posted -- but it'll also be a great starting place for people hoping to share their knowledge and expertise. Our initial stab at this is to list "limitations and goals" for a given kit, clearly explaining the problem we'd like to solve. This is actually a list of questions using our new questions system -- and we imagine people might post an activity, then link to it as a proposed answer.
We need your input!
This is all quite new, and we'd love to hear other ideas for how this could work. And of course, if you're interested in giving it a try and writing an Activity, please do! Activity grids are going up on many wiki pages across the site, so if you have questions about where and how to post, please leave them in the comments below. Thanks!
@cfastie says: "common pitfalls" (at #leaffest)! Great idea.
Reply to this comment...
Log in to comment
Ah! another -- "how many people are needed, or can do it together?"
Is this a question? Click here to post it to the Questions page.
Reply to this comment...
Log in to comment
We've been starting to work on a template, too!
Reply to this comment...
Log in to comment
At #leaffest-2016 we made a LOT of progress on activities! I noticed @kgradow compiled lots of existing #Coqui content into a grid at https://publiclab.org/wiki/coqui -- I added some tags too, and converted one activity to a question.
Reply to this comment...
Log in to comment
@liz -- are you really against our making an activity guide for how to write a good activity?
Is this a question? Click here to post it to the Questions page.
Reply to this comment...
Log in to comment
@warren, @liz -- I mentioned this at #leaffest-2016 but wanted to put it here as well.
I think that "common pitfalls" or "troubleshooting" or something like that is one of the most important parts of any howto/activity guide and it's worth really emphasizing it to people for a lot of different reasons.
1) Knowing that you have performed a set of troubleshooting processes and steps is one of the only things that will give a new user of a tool or technique confidence enough to believe that the problem they are experiencing might not be their fault. If part of the goal of activity grids, etc, is causing people to attempt replications, we need to make sure that replication "failures" are well documented and reported as well, since a lot of times they are evidence of something wrong with the activity.
2) Troubleshooting is absolutely the hardest part of every project so it's the part that people need the most support with. And because it's the part that requires deepest knowledge, it's also the part where the most learning happens. When you build/do something by following a bunch of steps, you can kind of get away without thinking hard about what they are or what you're doing as long as you are careful. But when something goes wrong and you have to do a lot of examination of what you're doing and thinking hard about it, so it's also the point in a project where the most learning happens.
3) "it didn't work" is both bad feedback to get on your project, and a bad feeling for newcomers to take away from the project. Telling people a lot about how it can go wrong and giving them a concrete set of things to do and say when reporting failure will improve the quality of feedback.
Reply to this comment...
Log in to comment
@wmacfarl this is really, really helpful.
1) we're working on how to document fails this week! We'll keep you posted.
2) Is there a good example of written/recorded documentation that achieves this that you could point us at? I have to confess i'm really not sure how to do this because it could potentially go in so many different directions (at least with microelectronics, but maybe i should imagine a simpler example...)
3) ^ same?
Is this a question? Click here to post it to the Questions page.
Reply to this comment...
Log in to comment
@wmacfarl, I completely agree with you there. Thanks for highlighting that.
I also think that we need to provide more feedback options than "success" and "failure." For example, the activity could be successfully replicated in that steps were clearly articulated and followed, but outcomes could be different, and that's not failure -- it's really important new knowledge; it's how we learn about precision, confounding factors, conditional features, etc. Maybe we could distinguish between activity replication and results congruence ?
Is this a question? Click here to post it to the Questions page.
Reply to this comment...
Log in to comment
Replication is a pretty big topic -- i put down some notes from a discussion we had among staff yesterday in this GitHub issue, looking forward to how we'll build out these features: https://github.com/publiclab/plots2/issues/786
But Github is a poor place to discuss this. We should put up another blog post all about replication!
Reply to this comment...
Log in to comment
I'm working on some activities for calibrating and deploying the MiniVol.
I posted my activities as a works-in-progress, because I had a two-step process:
My intention was to model activity replication and improvement by replicating my own activity (step 1) with improvements (step 2). Doing this, however, has left me with a messy-looking activity in the grid. It isn't clear which activity should be followed, the original Activity or the Replication.
I have a few more activities to update with images and notes. I could skip the replication stage and just go edit my original Activity post. This would give me a cleaner activity grid, but I don't like this option for a few reasons:
Only I can edit the original activity, so I'm not modeling a process others can join. There's no clear path for someone else who wants to improve my original activity to indicate they've replicated and improved it.
Research notes have no revision history. It's not clear what I changed and why. Imagine that someone had followed my instructions and posted a Replication. Based on issues encountered through replication, I edit the original Activity. It isn't clear what their Replication is referencing now.
My original Activity notes from the manual are more 'canonical' to the manufacturer/EPA instructions, and changes away from those instructions, while useful to actually getting the task done, could lead to drift over time. That drift should be traceable. Decisions made in one revision should be reversible later, either through a record of replications/improvements or a wiki-style revision history.
Is this a question? Click here to post it to the Questions page.
Reply to this comment...
Log in to comment
As a next step, i'd like to think about how to improve/update an activity that someone figures out while replicating the original activity. CC @mathew
Reply to this comment...
Log in to comment
For those kits or projects using software/computers, it would be handy for people to write down basics of their setup for the activity, as well as for posting questions:
Computer/model IOS version Public Lab software version Public Lab kit version
Reply to this comment...
Log in to comment
For those people using Public Lab software, it would be helpful to include set-up info for the activity or for posting questions:
Reply to this comment...
Log in to comment