< DRAFT+ >
Effective use patterns for the Etherpad+E2H collaborative system.
Table of Contents
→ See how the CHT/Totalism project uses it: a view of the extent & inter-linkage of the documentation here.
Some instructive pages:
→ — this page — Tips for using the system in practice.
→ E2H formal presentation: Features, Syntax, etc.
→ Setup 🔗workflow-bookmarklets (~1 minute of work), for easier Read/Edit mode switching
→ Generally important computer skills, especially keyboard shortcuts.
→ 🔗hypothesis — Using the "Hypothesis" annotations & highlights system
*** "ETHERBEAMER": Live crowd ethering
Not a "talk", not a "workshop":
[Pad + Projector + Steward + Crowd]
("Person" = Member of Crowd)
("People" = Crowd)
("Steward" = Event steward)
Two attempts at explaining this:
1) Facilitator comes on stage that also has a projector.
They open the Etherpad link on the network accessible to all.
2) The Etherpad contains an outline the facilitator wrote out 5 minutes ago.
That's basically a few points about the topic, and starts to rummage.
3) People open their laptops and join the pad, and just start typing away their thoughts.
4) The facilitator kind of curates what's going on on the pads:
Exposing some of the stuff that's written, and also writes themselves, especially giving thought to indenting and stuff like that.
Basically, they're like a "live action commentator" / steward in a way.
Example "workshop" like this:
(press PLAY and bear with it for ~10 seconds to start moving as it preloads)
It needs to feel like a high-spirited, positively manic debate, while several writers collaboratively note it all down, establish a "consensus log".
One of the important parts of the event steward's job is to consolidate & actively enforce note form.
So it helps if you're able to talk + write + MICRO EDIT at the same time.
My repeated experience has often been an awkward first 10 minutes - trying to open the debate fronts, break the distrust of the format, etc. Which reminds me - it really helps to come on stage and paint an initial picture of being an imperfect and "ill prepared" speaker (always my natural state anyway...), probably because it reinforces it is not a talk, and that this is just *a group of people gathered to discuss and orderly notate the shit out of a topic they all found interesting enough to put an hour of best effort into*.
... and then in the later minutes there's only worrying if etherpad/network will break down (etherpad no, networks sometime - so best to have your own).
It has mostly three modes:
I) "WILD PARALLEL MODE"
Most important is, you have to keep people from talking for more than a minute. Ideally they get to a point where they sketch their point on the screen beforehand, get called out, and just expand it/receive comments in the parallel talk discussion. You always only do one thing: seek to confirm that what's written down, captures what they're saying. Quickly, people seem to get that, and you get stuff like speakers stopping mid-point saying "yeah that's it" when it's been captured, or changing course as others are already reacting to it in writing. In a way, the hypertext & the talking have to keep colliding.
Of course you always prioritize people who haven't spoken and actively seek them out. These are welcome changes in rhythm, and also make people appreciate they have various levels of familiarity across the board. Many know more interesting things than they might thing. "Breeding discussion" is the main work, towards co-learning/educating.
[otherwise just fallback to...]
II) "ASKING QUESTIONS" / DIRECTLY ENGAGING
People who showed up obviously have an interest in the topic. What specifically was that? If nobody is knowledgeable or passionate enough to make points, then our collective reach must be at least asking really worthwhile questions, trying to figure out systemically why we're interested in this thing but "nobody knows anything about it?", etc.
You may ask for shows of hands, try to find the most surprising points that evoke reactions. An example of a good practice here is asking how many have thought of/support X, and then again how many are surprised by this.
This inter-active (hyper-active?) mode of knowledge/discovery has always brought amazing and surprising takeaways for me.
[otherwise just fallback to...]
III) "TALK MODE" + general
A perfectly noted-down thoughts of somebody that's kind of pretty knowledgeable about the topic. In practice for me, this might happen for a a few minutes at a time but always seems to get back on track.
Also, always seek others who are more knowledgeable than you on the subject, or parts of it. There have always been a few way good, and sometimes it hasn't been easy to find them, often because of their character - maybe they wouldn't ever normally organize a "lecture", but sometimes they end up throwing really great parts of it. As facilitator, you need to fish them out.
I suggest being coffee'd up, to spread that feeling. ;-) Also, keep showing the real-time E2H ( https://e2h.middlemachine.com ) results of the pad as well. "Llook at this actual document we're creating, not just another notes pad!". Importantly and somewhat paradoxically around focus, losing it is prevented by just jumping between topics a lot. You lose momentary "focus on specific topic", but keep a high energy ("group focus"). If the topic is important, the discussion will definitely return to it.
The biggest problem is at the beginning, with people thinking WTF, we're just jumping from one thing to another. Always one or two might want to quit, but these might be the best people who are passionate about the topics. You ask for patience, give them helms at that point about what their expectation was, and keep them. That's how you "seed" topics, inevitably hooking some people with each, and then just circle around them.
I always publish the pad in advance to try pre-collecting topics, but this does not happen. (It might if people would not always be first-timers to the format though).
At the end you are idealy mediating a bunch of tiny pad wars between many people writing.
Most people switch to having a center of attention somewhere between other people, the steward and the screen. It's also easy to see what to jump back to - people will monitor the screen and react to what's going on.
*** MAINTAINING & COLLABORATING ON PADS
* Don't even try to work on documents on mobile:
It works, but is a waste of time.
* Obviously, use CTRL+F in your browser to find stuff:
Use to navigate between syntax tags below!
* Learn and use other keyboard shortcuts:
* pg down / pg up
* ctrl+X , ctrl+V
More → 🔗workflow-basics !
* Don't delete stuff on your own:
Only cross it out!
Wait for co-editors to acknowledge, and (re)move the content.
Basic Collaboration Syntax (Conventions)
"###" == return to this
"!!!" == "bangs": fix this
"!!!!!!" == "multibangs" : higher priority fix
NAME TAGGING - involve others
tag people, for example on todos, with
(you can then find and cycle theirs/yours via Ctrl+F search)
">leo" == "for leo":
todo for leo!
">all !!!!!!" == "for all":
something very important for all to look at.
"<john" == "john>" == "from john":
john wrote this part
"+jessica" == "with jessica"
another person is involved / mentioned in what is written
--------------- (DEACTIVATED REFERENCE)
... the mention was deactivated for some reason (for example: task deferred, etc)
"NOW-POINTS" - current working location
CURRENT DOCUMENT WORKING LOCATIONS
Find them with ctrl+F.
"NEW-POINTS" or "FORKS" - space for new (un)sorted content
== "<------------ (new)"
Every living document should have at least one.
A drop-off point for new fragments, usually written above.
Sometimes as "NAMED FORKS" (for specific types of new entries)
== "<------------ (new) More forks examples ↑"
Cycle them with ctrl+F.
Links directly to pad.
Used most commonly for imperfect lists & sections to improve.
(for example when making comments)
"<john>", or a shortened version, "<j>"
(possibly, in early stage collaboration)
* always in new line!
* prefix with "--", which can be multiplicated:
--this is good!
ACKNOWLEDGE / "CHECK"
A space for participants to they "acknowledged!" or "checked!" a point.
The initiator opens it at some spot like this:
Others find it, and add their mark:
The spot has been provably "acknowledged" or "signed" !
(in the pad, you will see different colored 'x' due to authorship colors)
Marking a mess-ups: of style, indentation, syntax, etc.
If you got a correction:
Try to figure it out:
Look at how this is done elsewhere, you should be able to see it.
Documentation writing tips
Consider the purpose
What is the justification for writing (and for somebody else, reading) this?
Is this page not already covered by other, already existing sites?
(But: Maybe you just want a co-curated index of other materials)
Write Quality Documentation !!
From BAD to GOOD...
5) "unmarked grave":
a fragmented, long-winded ("detailed") log of a one-time event in an unmarked pad
4) "sensible notes":
foundation for a later-time analysis of "what went wrong / right"
(sensible next pass: bold the good lines)
3) "first distill":
short instructions, how to do it well (as a checklist, as "tips" and "caveats")
2) "draft protocol":
rewritten and improved existing instructions
1) "fully-fledged protocol":
regularly-used, perfectly positioned (indexed + a first-time user could find it), several repetitions, intuitive, wide-use
Accept Editor Corrections
// TMI //:
Too Much Information.
"Unmarked grave" category info.
This needs to be a fragment in a different place.
Otherwise it will get burried.
The least, move it to TITLED FRAGMENTS.
* Make sure you don't have public-intended documents "just sit there"!:
Even if they're not finished - publish them on an index!
* Don't leak links to internal documents
* Make sure they're at least kind of ok:
(or finish them to that state.)
* Mark them directly under title:
See "MARK DOCUMENT STATE" above.
[In-person group writing & coordination meetings]
As practised at CHT camps:
* Everyone has an active laptop (so they can participate in writing)
* No external service dependencies:
Local Etherpad server
* Often recorded:
(+ later timesynced to text)
* Standard agenda:
* first "overview" (pass through, comment on previous materials)
* then "review" (brainstorm new stuff)
* Regularity (about ~3 days)
Alternative Shared screen for groups
VNC can also be used to provide a shared screen (especially nice with tablets/mobiles!), instead of a projector
PROTOCOL: Cleaning up Very Dirty Pads
Pads will often get super messy.
Here's a placholder on how to resolve that.
* "Level zero" headers:
do a TOC overview
place some super (or "level zero") headers ("***")
* place proper "new-points"
* resolve major open todos!:
find "!!!!!!" and "??????"
* overview & merge previous unfinished agenda
* stage fragments:
* adopt a symbol system for frags in pad
TOC / header levels
* 0 = "***" (optional, if present)
* 1 = no indent
* 2 = first level of indent
* and so on ...
How to make links
### MERGE to manual
Ways to make links:
1) https://normal.link (WITH PROTOCOL)
2) LINK ON TEXT
* somelink.whatever.com - ADD THE PROTOCL ( http:// )
* www.blabla.com - THIS WORKS BUT ADD THE PROTOCOL ANYWAY
* how to understand and communicate links:
>david fix links !!
Indicating position inside a pad
(You don't need to say if it's in document/pad, as it's apparant.)
Read mode (documents):
* "2.1 in TOC!":
go to the "2.1" in Table of Contents
* "Read Planning!":
open 🔗planning (in READ MODE)
Edit mode (pads):
* "let's go to one forty four":
line 144 in pad:
and, INDICATE YOU ARE THERE ("use checks" - make an x)
* "let's work on protocol-going":
open that pad in EDIT MODE
Learn to work rapidly
* read and master 🔗workflow-basics !!:
"NOWPOINT" vs ""WORKING NOWPOINT" (double brackets)
a single document on a pod
a whole server, full of documents
the name also includes the infrastructure of running it
Styling basics aka "AWESOME CSS GUIDE"
See → 🔗styling
Cue: Follow! ("Eye" / "Watch")
Follow the current pad writer, in real-time.
* clicking top right ("authors")
* click color next to their name, to Follow
MARK DOCUMENT STATE
< STATE >
* STUB: placeholder or just a sketch
* PRE-DRAFT: pre-revised, document structure not fixed
* DRAFT: ready for final revisions
(some nice examples of collaborative docs, techniques)
* cool trick with getting people to sign themselves
* signature history demonstrates "follower" mentality (in the signature format)
do: fragment tagging!
(usually includes fragment tagging)
* "where are we"?:
pad + line number
* "find me tihs thing":
link to pad + linenumber
(Site generated by E2H, an "Etherpad hypermedia" project by @dcht00).
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.