The Pass Around Document (PAD) system

Background | Brief | Verbose | Comments | Tail

Translate

Background

Many good ideas have been presented on the KOSH mailing lists. Most of them have also been thoroughly discussed, but only a handful have been properly documented at the time of writing. Though some working groups have been formed they usually deal with long-term analysis or development, thus requiring long-term commitment from their members. Clearly this should not be needed just to analyse a simple idea.

Therefore the authors of this document concluded that a simple method should be offered to organize simple ideas, so we created the PAD.

Brief

A PAD is a work in progress, a document that is passed around within a small group. Each member holds the document for a while to suggest improvements, then passes it on to another member. This carries on until all members agree that it is ready for presentation.

Verbose

This section describes step by step how you go from a discussion to a finished document. Also included are descriptions of the structure of the PAD and how the rotation of it works.

Step 1 - forming the group

Suppose there is an interesting discussion. If you want it to actually lead to something concrete, ask if anyone else wants to work on a PAD discussing the topic.

PAD groups should consist of 2-5 people. Just one person does not make a group, while more than 5 people makes the group too large to function well. Three people is an ideal group size. If more than five people show interest, investigate if it's possible to divide the work across several groups.

Someone should be appointed to represent the group. Normally - but not necessarily - this would be the proposer. The representative should first check with the PAD organiser (pad@kosh.convergence.org) to make sure that the topic is not already being worked on. If clear, the representative should elect someone (normally themselves) to make a draft, the basic document. This process is described in Step 2.

Description 1 - the structure of the PAD

A PAD in work consists of three parts - a head, a body and a tail.

The head consists of two sections - Background and Brief. Background lists the reasons for writing the document, in essence a problem formulation. Brief describes in short the conclusion.

The body consists of the Verbose section (and perhaps some Comments). Verbose is the long description of the solution that the group has developed. Comments may consist of paragraphs that didn't quite fit within the descriptions in the Verbose part. In Comments you may also include some notes on how the result was obtained, but this is optional.

The tail contains a history of the document's creation. Even so, it is not to be neglected as it can very useful to the group and is also important to the PAD organiser. Please maintain it properly - see example. Please remove the tail and submit it to the PAD organiser for reference when complete.

Please follow the structure of this PAD when making your own PADs as it will then be easier for others to read, and much easier to process.

Step 2 - creation and approval of the draft

Write down your ideas, following the proposed PAD structure (see Description 1). Take good time, a good draft is perhaps not crucial to attain a good final document, but it certainly does help. Remember that you're writing a base for the group to improve and expand upon. Otherwise you may experience problems later on as the expanded document becomes harder to follow. When finished, sign the 'Draft created' line in the tail with name and date.

Then, before any modifications take place, the group must agree that the draft is usable as a base for further modification. If at least half the group are not satisfied then either another group member may try writing a new draft, or the topic is de-registered. The group may elect to stay together and work on a different topic or disband. See "if the draft is unused" and "if the group is disbanded" in Description 3 for more information about this.

Otherwise, if the draft is approved, the rotation process starts. This will eventually produce the final document, and is described in Step 3.

Step 3 - rotation (passing around the document)

This is the major point of the whole PAD process - to pass around the document, improving it further and further until the group is satisfied it is ready for publication. You should keep the order of rotation in a queue (see the tail). Before passing the PAD on, you should move your name from the top to the bottom of the queue. The representative decides the initial order. Please remember that the draft creator will probably not be interested in modifying his own work before anyone else.

When you receive the PAD, look at the queue. If your name is on top it's your turn to revise the document. See Description 2 for details on this procedure. When done, sign the history with 'Seen by:' followed by date and name, and a list of the modifications you made. If none, write 'unchanged'. You still hold the right to modify it later. Finally, send the PAD to the next person and copy it to the other group member(s) and the PAD organiser.

The above is repeated until everyone in the group has marked the PAD as unchanged in the same round. Then the representative asks if all members are satisfied with it. If they are, you may proceed to Step 4 - final adjustments.

Description 2 - how to make modifications, and the tagging system

All changes must be agreed to by the group. Until they are adopted by the group, they must be enclosed within tags. These examples show how it is done:

Addition

The addition tags shall enclose new sentences or sections. Instead of the full word addition you may just use the letter a, as in <!a> and </!a>.

Modification

The modification tags shall enclose sentences or sections that are modified from a previous state. Please leave the original text, enclosed within 'old' tags. Instead of the full word modification you may just use the first letters, as in <!m> and <!o>

Modification tags are not required for correcting typographical errors (i.e. adress -> address) because such changes do not affect the meaning of the text. Grammatical and punctuation errors may also be corrected directly - unless this has a potential of affecting the meaning of the text, in which case modification tags are recommended. If in doubt, contact the other members for clarification.

Nested tags

This is <!m ZZ>extremely fresh and new<!o>old and stale</!o></!m>.

As the document progresses, it is likely changes will be made to changes. Authors are advised to use common sense with modifications and not create messy structuring. Try to avoid changing anything within someone else's Modification tags. Creating a fresh copy of the sentence with changes, placing the old version in Old tags is strongly recommended:

This <!m YY>extremely dull sentence has been magically reworked. <!o>is <!m ZZ>extremely fresh and new<!o>old and stale</!o> </!m>.</!o></!m YY>

Note author 'YY' has signed the end tags of their changes, and used whitespace for legibility. Signing end tags is not a requirement, but can be useful in certain situations - use when appropriate!

Removal

The removal tags enclose sentences or sections that you would like to have removed entirely. Instead of the full word removal you may just use the letter r, as in <!r> and </!r>.

Moving

Before:
  This line used to have two sentences. But now it has two.
  This line used to have one.

After:
  This line used to have two sentences. <!cut#1>
  This line used to have one. <!mv#1>But now it has two.</!mv>

The ID is a numerical '1' in the above example but while we recommend you continuously number your IDs, it can be any short, unique identifier. If you decide not to use numerical IDs, please try to ensure IDs are meaningful and not similar to initials of PAD group members or tag names.

<!mv#1>, <!mv#001>, <!mv#Summary>, <!mv#Warning> are probably good choices.

<!mv#a>, <!mv#mv>, <!mv#JC>, <!mv#foobaryakkadidah>, <!mv#~@#&> are probably not good choices.

Initials

<!addition XX>This is a new fantastic sentence written by me, Xerxes Xylophone.</!addition>

If you agree with an existing suggestion, just add your own initials. You may also enclose an old addition which you don't agree with. If you disagree with a selection, add your initials prefixed by a lowercase x i.e. <!m xYY>

<!modification YY>The PAD group has written many good sentences. This is one of them. <!old><!addition XX>This is a new fantastic sentence written by me, Xerxes Xylophone.</!addition></!old> </!modification YY>

If you agree with part of the modification, approve the section and then modify it as normal.

<!modification YY, ZZ>The PAD group has written <!modification ZZ>a few decent <!old>many good</!old> </!modification ZZ> sentences. This is one of them. <!old><!addition XX>This is a new fantastic sentence written by me, Xerxes Xylophone.</!addition></!old> </!modification YY, ZZ>

When and how to make a suggestion permanent

When and how to remove a suggestion

Comments

They may look like this:

<!a XX; this is an expression, not a typo> A beer is a beer is a beer.</!a>

<!a XX, YY; an expression, got it :-) > A beer is a beer is a beer.</!a>

<! XX; You may also include separate comments like this one. These should not have an end tag.>

Finally

If you want to make lots of little changes to a sentence or paragraph, don't be afraid to copy the whole block to the Old part of a Modification tag and rewrite the sentence again with modifications - labelling clearly the start and end of the changes if they are large (hint initial all the tags <m! XX>...<!o XX>...<!o XX></!m XX>).

You may, at your option, circulate a preliminary version within the group to test the water before spending too much time on a new version.

Step 4 - final adjustments

The PAD may seem to be finished now to you, but people outside the group may disagree. Hopefully you have anticipated this and tried to get some input from these people already. Otherwise it's about time you do. A simple way of doing this is to post your PAD on whichever KOSH mailinglist feels most suitable. If you get some valid criticism, consider including the new ideas, but don't feel forced to (see "Input and output" in Description 3 for more about this).

Finally the PAD probably needs some cleaning up, spell checking, grammar correction, reformatting if needed, even translation if written in another language than English. How you arrange this is the representative's responsibility. The PAD organiser will not do any of the above for you.

What the PAD organiser will do for you is to format your PAD for presentation and submit it to the website. So when you are done, sign the 'Finished:' line with date and send it to (pad@kosh.convergence.org). If you want it formatted in a specific way please contact the PAD organiser rather than the webmaster.

The PAD representative is concerned with the content of the document - ASCII is currently the lowest common denominator for text content. The PAD representative should provide a fully proof-read copy in ASCII - that means spelling and grammar checked. This should at least be in English language, and ideally provided to translators for other languages.

The PAD organiser is concerned with the presentation of the document in assorted formats. The organiser is responsible for ensuring the document is at least available in plain text and standard HTML formats, two current primary distribution formats. An XML version is an ultimate aim, allowing the document to be stored in a portable and fairly future-proof way which eases conversion to a variety of formats such as plain text, HTML, WML, Postscript, PDF, or Palm DOC, as well as facilitate indexing, searching or versioning as the PAD changes over a period of time.

Description 3 - more about the PAD process

Input and output

A PAD group need not be a closed group. It doesn't have to be only your own ideas that you add to the PAD. In fact, you are encouraged to get input from people outside the group and if they want to see how your work is progressing, let them. Remember though that it is your work and outsiders cannot demand that you modify anything. If a person is very eager to help, the representative may, after having consulted the other members, decide to invite them to join the group. Please note guidelines on

group size

PAD groups may also be kept together (subject to the consent of participants) for the duration of more than one document's creation, should it be felt necessary to produce additional documents. Group members should not feel forced to continue. Should any feel they can no longer participate, they should inform the representative. They should then contact the PAD organiser and decide what should happen to the group.

Who should use the PAD?

While the PAD is intended as a simple system for allowing ideas to be formalised without too much formal structure, working groups are welcome to use this format where they find it helpful. The format may also be used when creating other works - design diagrams, web site, even source code - but please note that this is a use beyond the original design and so all problems that may be encountered are not our fault!

Timescale

Exactly how long it takes to complete a PAD cannot be said, it depends on the subject and the effort of the group members. As for one revision, one week to one month could be considered as normal. If a person takes too long doing their revision, the group may decide to let the next in turn continue instead. If this is repeated several times, consider erasing their name from the queue. Wherever possible, this should be done in consultation with the complete group. Should group relations fail, the PAD organiser should be consulted.

If the draft is unused

It's a possibility that a draft PAD is so bad that it serves no purpose, not even as a useful starting point for discussion. If someone feels that a draft PAD isn't worth discussing, they have the right to demand a rewrite.

The PAD should be made available to everyone in the group, whether it is their turn or not, and the group should decide whether the draft as it stands is usable. If a majority decide the document is unusable, they can either elect a new author to make a fresh draft or force the existing author to present a new draft. If the majority feel it is usable, but more than one person has considered the draft unusable, the current author should prepare a re-draft.

If the group is disbanded

If the group for some reason can't continue to function, for example if you don't succeed in creating an acceptable draft, or if too many members leaves the group, please don't simply discard your work. Instead, make sure that the PAD organiser as well as all group members knows what is going on. It's important that nobody is left in the dark.

Then, the topic discussed in the PAD is considered to be open information, so the PAD organiser will hand it over to another PAD group to evaluate. However, if the group consider the topic as a dead-end, due to it being useless and not worth discussing further, or the problem being unsolvable in theory or in practice, let the PAD organiser know this. Such topics should ideally not be discarded entirely, though, as another group may feel differentely and be able to make use of the document at a later date.

The fate of the drafts however is entirely in your hands. The PAD organiser will ask you to release them - or at least the latest one - to the public, so that they may be evaluated by other groups and perhaps even serve as a foundation for continued work. Although you aren't in any way forced to, we strongly recommmend that you give your permission to this. Perhaps you consider it to be of little value, but even small efforts may prove to be valuable.

Legal

While being created, the document is the property of the group collectively. No one member has power of veto over publication of the document or any part of it. The document may, however, be withdrawn at any stage subject to the consent of all who have worked on the document at any stage in its creation.

When the document has been submitted to the PAD organiser as complete, it becomes exclusive property of KOSH. At their option, KOSH may award payment in the form of virtual credits and / or red shares, but are in no way obliged to.

KOSH is unwilling to accept a PAD or work towards a PAD from anyone who will not consent to these terms. Before joining a group in any capacity, please mail the PAD organiser to indicate your acceptance of these terms.

While a PAD becomes the exclusive property of KOSH, KOSH must acknowledge the authors of a particular version of the PAD whenever such a document is presented in full.

Comments

No comments yet.

The tail

Group:		PAD

Representative:	Greg Webb

Other members:	John Chandler
		Marcus Petersson

Draft created:	27-28 Sep 1999, by Marcus Petersson

Finished:	not yet

The queue (top to bottom):

		Marcus
		Greg
		John

Seen by:	19th October, Greg Webb

Modifications:  Initial confirmation procedure added.
		Modified modification procedure (though it's not been entirely
		adhered to here as it's been agreed elsewhere, honest!)
		Minor style and grammar changes to tidy it up!
		Kommunity modified to Community, as with elsewhere.
		PAD organiser role created.
		Final, waffly paragraph added.

Seen by:        21st November, John Chandler

Modifications:	Minor corrections to typos.
		Slight modification to end of 2)
		Formalised the  tagging used by Greg on his turn
		Introduced concept of signed and anonymous Provisional tagging

Seen by:	25 Nov - 8 Dec, Marcus Petersson

Modifications:	Everything. :-)  To sum it up:
		Formalised structure (see description 1).
		New titles (see description 1).
		Introduced Step and Description titles.
		First use of subtitles.
		Actual changes of content:
		New sections Background and Brief slightly modified.
		Step 1, 2 and 4 modified from old text.
		Step 3 and Description 1-3 added, partly based upon old text.
		New tag system (see description 2).		
		More efficiant row usage (rows are now as long as possible upto
		max 80 characters). :-)

Seen by:	8 Dec - 11 Jan (oops...), Greg Webb

Modifications:	Little details and style cleanups all over the place!
		Tag system made marginally more coherent
		Hard linebreaks removed where possible to ease use on
                non-standard form factors. Most of this was done with my Palm
                III on the train!
                Legal bit added to try and cover us in case anything gets messy.
                Very sorry if this is getting too messy for people to read - I
                can follow it, but I can certainly see the sense in a dedicated
                PAD writer application...
                
Seen by:        22 Jan 2000, John Chandler

Modifications:  Minor reformatting, i.e. placing examples on new lines
                Minor addition to new Legal section
                Modifications and clarifications with certain tags.
                Added and formalised Cut and Moved tags (Marcus' initial suggestion)
                Added 'If the draft is wrong' 

Seen by:        4-13 Feb, 3-7 Mar, Marcus Petersson

Modifications:	Lots of tag removals. Lots of old text removals.

		In Step 1: Changed recommended group size.
		In Step 2: Slight change at the end. Some info moved to Desc 3.
		In Description 2: Modified almost all sections, mostly new examples.
		   Moved a section. Changed all example initials to XX, YY, ZZ.
		In Description 3: Minor modification. Moved two sentences.
		   New section: If the group is disbanded.

Seen by:        9 Mar - 19 Apr, Greg Webb

Modifications:	Some section aproovals
		Detail changes all over the place
		Introduced concept of disaprooval siqning.
		Comments all over the place. Sorry Marcus ;-)

Seen by:        19 Apr - 6 May, John Chandler

Modifications:  Removal and cleanup of tags
                Slight minor changes
		Formalised Greg's 'xYY' disagreement signing

Background | Brief | Verbose | Comments | Tail

The Pass Around Document (PAD) system

Brief

Verbose

Step 1 - forming the group

Addition

Modification

Nested tags

Removal

Moving

Initials

When and how to make a suggestion permanent

When and how to remove a suggestion

Comments

Finally

Step 4 - final adjustments

Input and output

Timescale

If the draft is unused

Comments

The tail