Ethering
< DRAFT++ >
Table of Contents
¶INTRODUCTION
A highly effective ideation, organization & publication model, using Etherpad and 🔗E2H software.
This document gives a functional introduction, at all levels — basic, intermediate & advanced.
An example:
The CHT/Totalism knowledge commons.
The public website has been assembled by hundreds of participants accross 10 years, and maintained by a full-time editor. The "internals" are an extended document set (staged to release, limited access, etc), accessible only to a core-group of operators.
a view of the extent & inter-linkage of the documentation here.
A highly effective ideation, organization & publication model, using Etherpad and 🔗E2H software.
This document gives a functional introduction, at all levels — basic, intermediate & advanced.
An example:
The CHT/Totalism knowledge commons.
The public website has been assembled by hundreds of participants accross 10 years, and maintained by a full-time editor. The "internals" are an extended document set (staged to release, limited access, etc), accessible only to a core-group of operators.
¶* Documents (or "pads") are contained in a pod.
A pod can have thousands of documents, that can be edited by many people at the same time.
The name also includes the infrastructure that powers it.
A pod can have thousands of documents, that can be edited by many people at the same time.
The name also includes the infrastructure that powers it.
¶* You can open documents either in VIEW or EDIT mode.
The difference is the first part of the link, before the document name.
You can find the EDIT button on each VIEW page!
### [!] make reverse true as well ...... @@e2h-todo
### [!*] consider hiding "Edit CSS" by default (as nobody does it EVER) ........ @@e2h-todo
Tip: For reverse and practicality, we reccomend trying to set up the 🔗workflow-bookmarklets.
The difference is the first part of the link, before the document name.
You can find the EDIT button on each VIEW page!
Tip: For reverse and practicality, we reccomend trying to set up the 🔗workflow-bookmarklets.
¶* VIEW mode is ... normal websites
Rich-text ("hypermedia") documents — with structured text, images, graphs, charts, and videos; you can follow links both inside ("internal links"), and outside the pod.
Rich-text ("hypermedia") documents — with structured text, images, graphs, charts, and videos; you can follow links both inside ("internal links"), and outside the pod.
¶* EDIT mode is ... real-time collaborative writing
Any number of people can edit the document simultanously, at the same time.
Every change is automatically saved, there is no special save button.
All changes persist, and can be easily rolled back. (So, nobody can break or vandalize things).
It's reccomended that when editing, you open the documents side-by-side, and refresh the
Any number of people can edit the document simultanously, at the same time.
Every change is automatically saved, there is no special save button.
All changes persist, and can be easily rolled back. (So, nobody can break or vandalize things).
It's reccomended that when editing, you open the documents side-by-side, and refresh the
¶* Editing is trivially simple
* You open the edit link.
* You scroll up and down the document.
* You position the cursor where you want to add something.
* You start writing.
* You open the edit link.
* You scroll up and down the document.
* You position the cursor where you want to add something.
* You start writing.
¶* Learning basics of computer use will help you use the system more effectively.
You might not consider yourself a "computer person".
But this is not about computers, but about collaborating with other people.
###AWK (You don't need to be a car person, but you still need to understand the simple basics of driving to stay on the road ... Except if you have a chauffer.)
You might not consider yourself a "computer person".
But this is not about computers, but about collaborating with other people.
¶* Your contribution to the pod is essential !
When collective adopted the pod system as the way to organize together, ideas expressed in other means (in chats, emails, unwritten conversations, etc) — will not reach others in the same way.
You might currently be more used to another system of interacting, but you should soon see the clear benefits of structured collaboration.
they do if you would express them in the pad system.
... Except if the chauffeur will write them for you.
When collective adopted the pod system as the way to organize together, ideas expressed in other means (in chats, emails, unwritten conversations, etc) — will not reach others in the same way.
You might currently be more used to another system of interacting, but you should soon see the clear benefits of structured collaboration.
¶* Work with the pod keepers
Every collective appoints Mentors & Editors, which will make sure you are successful in contributing to the collective.
With their help, you will progressively master good contribution practices!
Every collective appoints Mentors & Editors, which will make sure you are successful in contributing to the collective.
With their help, you will progressively master good contribution practices!
¶* Keep improving
By learning the more advanced concepts, you can significantly increase your collective's expressive power, and also help others.
By learning the more advanced concepts, you can significantly increase your collective's expressive power, and also help others.
¶* Learn & remember basic keyboard shortcuts
Basic keyboard use is not difficult to learn and essential to good productivity.
See → 🔗workflow-basics !
Learn to work rapidly.
ctrl+pg up/down
etc
------------------------
[!] >david : make a test app ;-) ........ #dev.ideas
Basic keyboard use is not difficult to learn and essential to good productivity.
See → 🔗workflow-basics !
¶* Don't even try to work on documents on mobile
It works, but is a waste of time except in emergencies.
You will be much more effective & comfortable on a laptop.
It works, but is a waste of time except in emergencies.
You will be much more effective & comfortable on a laptop.
¶* Search for content within the document
Use Ctrl+F in your browser to find things.
This will be especially useful with the syntax tags below!
Use Ctrl+F in your browser to find things.
This will be especially useful with the syntax tags below!
¶* Learn and use other basic keyboard shortcuts
* Pg Up / Pg Down
* Ctrl+X , Ctrl+V
More → 🔗workflow-basics !
* Pg Up / Pg Down
* Ctrl+X , Ctrl+V
More → 🔗workflow-basics !
¶* Never delete content on your own
It's a good practice to only strike it out!
Wait for Editors to acknowledge, and (re)move the content.
It's a good practice to only strike it out!
Wait for Editors to acknowledge, and (re)move the content.
¶* Styling & headering 101
Unlike Mediawiki, Markdown and other similar systems, Etherpad does this without syntax!
¶ * Just use Etherpad's text styles!
To style the text, just use the Etherpad styles:
Bold (Ctrl+B) , Italic (Ctrl+I), Underline (Ctrl+U).
(and combinations thereof)
To style the text, just use the Etherpad styles:
Bold (Ctrl+B) , Italic (Ctrl+I), Underline (Ctrl+U).
(and combinations thereof)
¶* Live collaboration: Following positions & moving within pads
(You don't need to say if it's in document/pad, as it's apparent.)
¶ → "Line 64"
You'll be asked to navigate to the edit mode of the pad,
or you will want to bring a position to the attention of other people.
Line numbers are marked on the left of the editor.
* "let's go to one forty four":
line 144 in pad. and, INDICATE YOU ARE THERE ("use checks" - make an x).
* "2.1 in TOC!":
You'll be asked to navigate to the edit mode of the pad,
or you will want to bring a position to the attention of other people.
Line numbers are marked on the left of the editor.
¶ → "Check!"
("Acknowledge!")
== "[xxxx]"
A space for participants to they "acknowledged!" or "checked!" a point.
The initiator opens it at some spot like this:
"[x]"
Other participants find it & and add their mark:
"[xxxx]"
The spot has been provably "acknowledged" or "signed" !
(in the pad, you will see different colored 'x' due to authorship colors)
== "[xxxx]"
A space for participants to they "acknowledged!" or "checked!" a point.
The initiator opens it at some spot like this:
"[x]"
Other participants find it & and add their mark:
"[xxxx]"
The spot has been provably "acknowledged" or "signed" !
(in the pad, you will see different colored 'x' due to authorship colors)
¶ * Auto-generated Table of Contents
add "[TOC]"
bold+underline text to create a heading
drop increments of 4 spaces for subheadings
helps a lot with content organisation!
add "[TOC]"
bold+underline text to create a heading
drop increments of 4 spaces for subheadings
helps a lot with content organisation!
¶ * Images by URL, via upload, or from other Pods
like "[img:https://example.com/test.png|width]"
width: "50%" or "300px".
like "[img:https://example.com/test.png|width]"
width: "50%" or "300px".
¶ * Adopt Styles from other pads ("-css")
a) "[style]" declaration:
[style:padname].
(includes "padname-css" pad as a stylesheet)
b) with url parameter "CSSPAD":
Example: http://localhost/CHT/E2H/e2h.php?_=cht5-frags&CSSPAD=hyperphoto
a) "[style]" declaration:
[style:padname].
(includes "padname-css" pad as a stylesheet)
b) with url parameter "CSSPAD":
Example: http://localhost/CHT/E2H/e2h.php?_=cht5-frags&CSSPAD=hyperphoto
¶ * Image galleries (from Pods, or local storage)
like "[###:part_of_filename]"
(Example on ### page.)
¶ * Text-to-Graph (flowcharts, diagrams, networks, etc)
using the "[graph]" directive & an own intermediate language
details → 🔗glia-graph
example → 🔗graph-index
using the "[graph]" directive & an own intermediate language
details → 🔗glia-graph
example → 🔗graph-index
¶ * Include maps
Allows referring to Google MyMaps, a collaborative editor for public maps.
* use as: "[gmap:google_mid|label]"
* gives rendered link with .kmz and .gpx exports
* (with Mirrorable) makes automatic offline backups
* see on 🔗maps (the top list)!
Allows referring to Google MyMaps, a collaborative editor for public maps.
* use as: "[gmap:google_mid|label]"
* gives rendered link with .kmz and .gpx exports
* (with Mirrorable) makes automatic offline backups
* see on 🔗maps (the top list)!
¶ * Include content via Date
as "[date:YYYY-MM-DD]" and then "[date++]"
This auto-includes related content (images, ...) from the archives, as subheadings.
Also useful as activity logs.
as "[date:YYYY-MM-DD]" and then "[date++]"
This auto-includes related content (images, ...) from the archives, as subheadings.
Also useful as activity logs.
¶Access Levels
Within a single pod, you will usually operate with documents
3 = public
2 = internal / members
1 = leadership
Often, a document will have a main level (for example 3), with an aux document at another level (for example, 2):
Two second will point to the first.
### [!!] E2H— solve this programmatically
Within a single pod, you will usually operate with documents
3 = public
2 = internal / members
1 = leadership
Often, a document will have a main level (for example 3), with an aux document at another level (for example, 2):
Two second will point to the first.
¶ "BANGS", "HASHES": Marking tasks & improvement parts
[!!!] document the new, header-level syntax
"!!!" == "bangs": fix this (content), or, do this (task)
→ prioritized tasks to work on
"$$$" == "currently working on this"
→ one or few
"###" == return to this
→ many, not top priority
"!!!" == "bangs": fix this (content), or, do this (task)
→ prioritized tasks to work on
"$$$" == "currently working on this"
→ one or few
"###" == return to this
→ many, not top priority
¶ NAME TAGGING: Involving others
This is useful for collaboration.
You can easily find people with a 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)
"_jessica"
... the mention was deactivated for some reason (for example: task deferred, etc)
This is useful for collaboration.
You can easily find people with a 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)
"_jessica"
... the mention was deactivated for some reason (for example: task deferred, etc)
¶ SIGNED COMMENTS & INLINE CONVERSATIONS
(possibly, in early stage collaboration)
"<john>", or a shortened version, "<j>"
when replying, you should use:
<<<jane
you can also add a date, like
<<<junior , 2022-02-12
(possibly, in early stage collaboration)
"<john>", or a shortened version, "<j>"
when replying, you should use:
<<<jane
you can also add a date, like
<<<junior , 2022-02-12
¶ * "GENERAL NOW-POINT" (for new, unsorted content)
== "((NOW))"
(with double brackets)
Usually at the end of the document.
== "((NOW))"
(with double brackets)
Usually at the end of the document.
¶ * "NOW-POINTS" (current working location)
== "(NOW)"
== "$$$$"
CURRENT DOCUMENT WORKING LOCATIONS
Find them (Ctrl+F)
== "(NOW)"
== "$$$$"
CURRENT DOCUMENT WORKING LOCATIONS
Find them (Ctrl+F)
¶ * "NEW-POINTS" or "FORKS" (space for new unsorted content)
== "<------------ (new)"
Cycle them with Ctrl+F.
Any 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)"
Cycle them with Ctrl+F.
Any 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)
¶ * Header levels
Levels:
* 0 = "***" (optional, if present)
* 1 = no indent
* 2 = first level of indent
* and so on ...
Levels:
* 0 = "***" (optional, if present)
* 1 = no indent
* 2 = first level of indent
* and so on ...
¶ * Making links (to other documents)
GOOD:
1) https://normal.link (WITH PROTOCOL)
2) LINK ON TEXT
3) 🔗example
4) TLM🔗another-pod
BAD:
* somelink.whatever.com - ADD THE PROTOCL ( http:// )
* www.blabla.com - THIS WORKS BUT ADD THE PROTOCOL ANYWAY
GOOD:
1) https://normal.link (WITH PROTOCOL)
2) LINK ON TEXT
3) 🔗example
4) TLM🔗another-pod
BAD:
* somelink.whatever.com - ADD THE PROTOCL ( http:// )
* www.blabla.com - THIS WORKS BUT ADD THE PROTOCOL ANYWAY
¶Corrections from Editors
Accept editorial marks. (aka ANNOYANCE MARK)
== "¤¤¤"
You made a mess with style, indentation, syntax, etc:
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"
__________________________
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.
//MISPLACED//:
This needs to be a fragment in a different place.
Otherwise it will get burried.
The least, move it to TITLED FRAGMENTS.
Accept editorial marks.
== "¤¤¤"
You made a mess with style, indentation, syntax, etc:
Try to figure it out.
Look at how this is done elsewhere, you should be able to see it.
__________________________
//TMI//:
Too Much Information.
//MISPLACED//:
This needs to be a fragment in a different place.
Otherwise it will get burried.
The least, move it to TITLED FRAGMENTS.
¶Consider document 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)
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 !!
5=bad, 1=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
5=bad, 1=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
¶Keep publishing
* 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.
* 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.
¶Marking document state
Like this:
< STATE >
:
* STUB: placeholder or just a sketch
* PRE-DRAFT: pre-revised, document structure not fixed
* DRAFT: ready for final revisions
* RFC: publicly released and basically finished, needs readers & editors
### consider with XXX🔗padwork marks system ...
Like this:
< STATE >
:
* STUB: placeholder or just a sketch
* PRE-DRAFT: pre-revised, document structure not fixed
* DRAFT: ready for final revisions
* RFC: publicly released and basically finished, needs readers & editors
¶Simple & powerful theming
1) Default style if not specified:
https://pad.totalism.org/p/CSS-default
(or equivalent in your install)
2) Every site takes the "sitename-css" pad as CSS:
example: this page, 🔗E2H, takes 🔗E2H-css
(There is also a link to "Edit CSS" on each site, if not hidden.)
3) Via style imports inside the pad:
"[style:padname]" will adopt a stylesheet, defined in the "padname-css" pad.
4) Via URL in optional parameter:
"&customcss=http://e2h.middlemachine.com/E2H/css.css"
Use the above .css file as the base for your theme.
If you want to just mess with the colors a bit, it's best to find+replace current colors (which are used several times inside the .css).
5) Set custom theme via pad:
"&CSSPAD=padname"
1) Default style if not specified:
https://pad.totalism.org/p/CSS-default
(or equivalent in your install)
2) Every site takes the "sitename-css" pad as CSS:
example: this page, 🔗E2H, takes 🔗E2H-css
(There is also a link to "Edit CSS" on each site, if not hidden.)
3) Via style imports inside the pad:
"[style:padname]" will adopt a stylesheet, defined in the "padname-css" pad.
4) Via URL in optional parameter:
"&customcss=http://e2h.middlemachine.com/E2H/css.css"
Use the above .css file as the base for your theme.
If you want to just mess with the colors a bit, it's best to find+replace current colors (which are used several times inside the .css).
5) Set custom theme via pad:
"&CSSPAD=padname"
¶Hypothes.is annotation support
See → 🔗hypothesis !
Use either:
A) via URL addition:
add "&hypo" OR "&hypo&stick" (to include annotation mode in following links)
B) by adding to any pad (to enable annotating there default):
"[HYPOTHESIS]".
See → 🔗hypothesis !
Use either:
A) via URL addition:
add "&hypo" OR "&hypo&stick" (to include annotation mode in following links)
B) by adding to any pad (to enable annotating there default):
"[HYPOTHESIS]".
¶Leading reviews
### stub[!!]
[In-person group writing & coordination meetings]
Editors will lead "overviews", where:
* 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, [...]
[In-person group writing & coordination meetings]
Editors will lead "overviews", where:
* 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)
* Regularity (about ~3 days)
¶Cleaning up Very Dirty Pads
(Protocol)
Pads will often get super messy.
Here's a placeholder 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
Pads will often get super messy.
Here's a placeholder 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 "??????"
find now-points
* overview & merge previous unfinished agenda
* stage fragments:
adopt a symbol system for frags in 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
Also see → 🔗ethering-beamer !
VNC can also be used to provide a shared screen (especially nice with tablets/mobiles!), instead of a projector
Also see → 🔗ethering-beamer !
¶* Optional URL parameters (for single page rendering)
$$$$$$
Basic:
* &STYLE to include CSS styling
* &BTN to include 'Edit pad' button at the bottom
* &BTNCSS to include "Edit CSS" buton
* &css=[XXX] specify one of the built-in themes (found in E2H folder as css-XXX.css)
* &customcss=[path to .css file] specify own .css theme. See Theming above.
Extra:
* &noAnchors to disable autoinserting anchors on underline+bold text
* &noTOC to disable TOC, even if inserted into page
* &DEBUG to enable DEBUG mode
* &CSSPAD=[padname] to, like with [style:...] directive, apply 'xxxxxx-css' to any doc
___ ___ ___ ___ ___ ___ ___
Future:
* specify content license
* "Edit pad" button position: top/bottom/side
* enable navigation in header (by specifying link to pad with a list of items)
Basic:
* &STYLE to include CSS styling
* &BTN to include 'Edit pad' button at the bottom
* &BTNCSS to include "Edit CSS" buton
* &customcss=[path to .css file] specify own .css theme. See Theming above.
Extra:
* &noAnchors to disable autoinserting anchors on underline+bold text
* &noTOC to disable TOC, even if inserted into page
* &DEBUG to enable DEBUG mode
* &CSSPAD=[padname] to, like with [style:...] directive, apply 'xxxxxx-css' to any doc
___ ___ ___ ___ ___ ___ ___
Future:
* specify content license
* "Edit pad" button position: top/bottom/side
* enable navigation in header (by specifying link to pad with a list of items)
¶* Per-Instance configuration
Manage instance details (/__LOCAL_CONFIG)
Manage Pods (/__LOCAL_RELINKING)
Manage instance details (/__LOCAL_CONFIG)
Manage Pods (/__LOCAL_RELINKING)
¶* LAN-only autoconfiguration
(Host a Localnet instance with no Internet connection).
Useful for deployments on laptops as Etherpad+E2h servers, retaining functioning links, ...
(Host a Localnet instance with no Internet connection).
Useful for deployments on laptops as Etherpad+E2h servers, retaining functioning links, ...
¶* Linkroute: A way to refer to other Pods
Discovers and routes to content on local machine, physically accessible resources (external drives), and from other trusted nodes (in a distributed / P2P DNS way)
Discovers and routes to content on local machine, physically accessible resources (external drives), and from other trusted nodes (in a distributed / P2P DNS way)
¶* Mirrorable: Offline regular backups
Uses E2T + cronjobs + DISTRO + git + git gui.
Stores: .txt and .html versions.
Uses E2T + cronjobs + DISTRO + git + git gui.
Stores: .txt and .html versions.