< DRAFT+ >

Effective use patterns for the Etherpad+E2H collaborative system.
collaborative hypermedia system / document system


An example:

→ See how the CHT/Totalism project uses it: a view of the extent & inter-linkage of the documentation here.

Some instructive pages:
Ties to 🔗ethering, 🔗workflow-basics, XXX🔗workflow-ethering, etc.

→ — 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

###consider improving with for example and other similar docs

*** "ETHERBEAMER": Live crowd ethering

Not a "talk", not a "workshop":
    [Pad + Projector + Steward + Crowd]

(Interaction graph)


Actor Actor Steward interactions during talk Steward interactions during talk Other interactions Other interactions

("Person" = Member of Crowd)
("People" = Crowd)
("Steward" = Event steward)
engage and direct->people people->monitor people->predominant reaction to people->listens to monitor->shared screen predominant reaction to->shared screen predominant reaction to->steward listens to->person micro-editing->pad pad->displayed on steward->engage and direct steward->listens to steward->micro-editing steward->outlining (before event) steward->note taking steward->asks question to steward->points to steward->protocol intervention outlining (before event)->pad note taking->pad asks question to->people points to->shared screen protocol intervention->people person->monitor person->note taking person->protocol intervention person->writing own content person->intervention displayed on->shared screen writing own content->pad intervention->steward engage and direct engage and direct people people monitor monitor shared screen shared screen predominant reaction to predominant reaction to listens to listens to micro-editing micro-editing pad pad steward steward outlining (before event) outlining (before event) note taking note taking asks question to asks question to points to points to protocol intervention protocol intervention person person displayed on displayed on writing own content writing own content intervention intervention

Two attempts at explaining this:

(Simple Explanation)

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)

Final result:

(Detailed Explanation)

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:


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...]


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 ( ) 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.




    * 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)

        --------------- FOR
        ">leo" == "for leo":
            todo for leo!
        ">all !!!!!!" == "for all":
            something very important for all to look at.

        --------------- FROM/BY/VIA
        "<john" == "john>" == "from john":
            john wrote this part

        --------------- WITH
        "+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
    == "(NOW)"
    == "$$$$"

        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.

    == "[...]"

        Contribute here!
        Links directly to pad.
        Used most commonly for imperfect lists & sections to improve.
        ### difference from now-points ?


        (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!
            ----I agree

    == "[xxxx]"

        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.

    1) correct mistake
    2) note mistake down (to your log)
        write it down here, on XXX🔗editorial
    3) acknowledge:
        "corrected & noted down in X"

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 !!

### //STUB//

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

There will be a "CORRECTIONS" section in non-published collaborative documents.
Corrections will be addressed to you from any editors.
Cross-out a correction to acknowledge.

// 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.

[...] ###

    Publishing Documents

* 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.

Advanced / In Development / Customary Syntax
See XXX🔗padwork and XXX🔗symbols.


### stub
[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
        Local network

    * Often recorded:
        (+ later timesynced to text)

    * Standard agenda:
        * first "overview" (pass through, comment on previous materials)
        * then "review" (brainstorm new stuff)
        ### link to more agenda docs

    * Regularity (about ~3 days)

#TODO: document, based on CHT🔗reviews !
See CHT🔗cht-metaprotocol, [...]

*** PAD

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.
### merge in other notes on this !!!!!!

    * "Level zero" headers:
        do a TOC overview
        place some super (or "level zero") headers ("***")

    * place proper "new-points"

    * resolve major open todos!:
        find "!!!!!!" and "??????"
        find now-points

    * overview & merge previous unfinished agenda

    * stage fragments:
        * adopt a symbol system for frags in pad
        * [...]

    * [...]

(some BASICS)

    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: 
    3) 🔗example
    4) TLM🔗another-pod

    * - ADD THE PROTOCL ( http:// )

* 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 !!:
        ctrl+pg up/down
    * >david : make a test ;-) ###


"NOWPOINT" vs ""WORKING NOWPOINT" (double brackets)


* pad:
    a single document on a pod

* pod:
    a whole server, full of documents
    the name also includes the infrastructure of running it

* [...]

    Styling basics aka "AWESOME CSS GUIDE"

See → 🔗styling
#e2h #TODO : must come with every pod

    Cue: Follow! ("Eye"  / "Watch")

Follow the current pad writer, in real-time.

    * clicking top right ("authors")
    * click color next to their name, to Follow 

### !!! this doesn't seem to work 2020-10


like this:
    < STATE >

    * STUB: placeholder or just a sketch
    * PRE-DRAFT: pre-revised, document structure not fixed
    * DRAFT: ready for final revisions
### consider with XXX🔗padwork marks system ...

(some nice examples of collaborative docs, techniques)
* async
* cool trick with getting people to sign themselves
* signature history demonstrates "follower" mentality (in the signature format)

do: fragment tagging!


do: folding!

(usually includes fragment tagging)

<---------------------------------------------- ((new))

more cues
* "where are we"?:
    pad + line number
* "find me tihs thing":
    link to pad + linenumber

(Site generated by E2H, an "Etherpad hypermedia" project by @dcht00). Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Edit Site

Edit CSS