Extended Contributor Guide

From Spindle Law Wiki

1 Organization of the Spindle Tree
2 The Text of the Topic, Rule, and Reference
3 Add, Edit, Move, and Delete Branches

Organization of the Spindle Tree

Spindle organizes the law into a tree, with each branch an area of law that grows narrower branches for topics, rules, and references, guiding legal researchers to the legal rules they're after. The tree consists of

Topics
Topics are issues or legal concepts that are groupings of sub-topics or rules. Topics may be broad or very narrow. A topic is a concept that would not be followed with a citation to an authority. Topics that group contradictory sub-topics or rules are called "split topics."
Rules
Rules are propositions of law, or any statement that can be supported with a citation to an authority. That includes justifications or history. Where a rule has an exception(s), it is called a "general rule."
References
References are mechanisms for leaping to related parts of the tree. A "cross-reference" takes you to a different, existing part of the tree. A "pollinator" is a placeholder for an area of the tree that needs to be created; once that area is built, the pollinator will become a cross-reference.

Legal issues are organized on Spindle to follow the logic of the law. The organization is generally like that found in a judicial decision or formal legal memorandum. Creating the organization of any legal issue is more art than science, and if given the same legal issue to organize, Spindle contributors might organize it somewhat differently. No matter the details of the organization, however, at a more general level the organization will tend to follow predictable paths, which will make sense to lawyers and that lawyers will be expecting.

Topic, rules, and references are organized so that they relate as parents, children, and siblings.

A parent is a topic or rule that has sub-topics or sub-rules. Those sub-topics and sub-rules are its children.
A child can also be a parent. That is, a given rule may have a topic or rule as its parent as well as a sub-topic or sub-rule as its child.
A rule's children are dependent on the parent rule. A rule's children include, for example, narrower applications of the rule, rules that follow as a logical consequence of the rule, justifications for the rule, and exceptions to the rule.
Siblings are topics or rules that have a common parent.
Siblings that contradict one another have a parent that is designated as a "split topic." Note that the children and other descendants of the contradictory siblings will also likely contradict one another, at least implicitly.
A general rule—a rule that has exceptions—is the parent of its exceptions. If it adds clarity, though, topics may intervene between the general rule and exception. That is, the general rule may have a child-topic whose children are exceptions to the general rule.
A cross-reference does not have any sub-topics or sub-rules.
A pollinator may include sub-topics, sub-rules, and sub-cross-references, so that the new area of the tree that it stands for can begin to develop.

Spindle's organizational structure is hierarchical and highly vertical. A topic or rule should have no more than seven children. That is because seven is about the maximum number of items a person can hold in her mind at once. Contributors can create more than seven children for drafting purposes, but the final version should never include more than seven.

The topics and rules in the tree should be organized by concept. This goes even for areas of law that are governed primarily by statutes and regulations rather than case law: The structure should follow the conceptual logic of the statute or regulations which may or may not coincide with the organization in their enacted or promulgated form.

When contributing to the tree, keep in mind the following assumptions about Spindle researchers. These are generalizations, but targeting these researchers will maximize Spindle's usefulness. Assume that Spindle users are:

lawyers,
novices or experts in the legal practice area or issue they are researching,
starting with a set of facts—known, alleged, or hypothetical—and that some of the facts may be unknown,
conducting research on Spindle to determine how the law applies to known facts and/or to determine what still-undetermined facts would be relevant.

The Text of the Topic, Rule, and Reference

Topics and rules are expressed in a "short text" and "long text." The "short text" of the topic or rule appears in the Narrow Down menu box and the red navigation trail. Clicking on the short text opens that topic or rule, which is stated in the "long text" and shown in the center of the screen when browsing.

The short text

means exactly the same thing as the long text, except that it omits what is understood from the rule's position in the tree; it does not omit anything more than that and is not a title or heading for the long text.
states the topic or rule very briefly, using no more than a few words. If it can't be expressed in just a few words, you probably need an additional topic or two between the topic or rule and its parent.
relies on ancestor topics and rules to make its context fully clear, and does not repeat concepts or text from ancestor topics and rules.
allows the researcher to understand the topic or rule without clicking on it to open the long text.
may be a single word. Many rules, for example, can be expressed in the short text with a simple "Yes" or "No," because they are read in context with the short text of the ancestor topics and rules.
may include abbreviations.
may end with an ellipsis in exceptional circumstances in order to indicate that the entire idea of a topic or rule has not been expressed. One situation in which this is appropriate is where the rule includes a list of items that must be included in a single rule (although they may also be dealt with individually in separate rules). For example, the short text of a rule stating the elements of a claim may be "Elements are . . . ," and the elements may be stated in full in the long text.
of a rule states the rule (e.g. "Permissible" states a rule; "Permissibility" does not).

The long text

states the whole topic or rule in a way that is clear even out of context, revealing what the topic or rule does and does not encompass. (It should not depend on context because the researcher may come to the rule from anywhere: from browsing on Spindle, doing a Spindle search, or from a web search from outside of Spindle; and because, in the case of a rule, it is intended to stand alone in a SpinDoc or in a legal brief or memorandum.)
despite being longer than the short text, does not contain any information that could not be understood from the short text and the position of the branch in the tree.
is a single complete sentence stated in the way it would be in a legal memorandum or brief. The long text of a rule will be inserted into SpinDoc when the researcher wants to include it in a legal document.
of a topic is a noun or a noun phrase (e.g., "Whether accountants can be liable under 10b-5.").
ends in a period.
of a topic does not list sub-topics that fall within it. Rather, the sub-topics are children—visible in the Narrow Down menu box—and not included in the long text. For example, the long text to the topic Defenses to a Rule 10b-5 claim is "Defenses to a claim for primary liability under Rule 10b-5." And not "Defenses to a claim for primary liability under Rule 10b-5 are time bars, immunity, waiver."

Add, Edit, Move, and Delete Branches

You can add, edit, move, or propose a deletion of topics, rules, or references at any point in the tree, creating the organization for a whole new legal issue, or expanding on an existing one.

Before contributing, please

review the discussion above about Spindle's organizational principles, the rule of seven, and the assumptions about Spindle researchers.
if you are expanding a legal issue already found on Spindle, become familiar with that section, as well as related areas.
- Topics and rules should not be repeated. Use both browse and search to confirm that you are not adding a duplicate.
- Use cross-references to link to related, pre-existing material.
- If you move a topic or rule from another area into the area you are building, use a cross-reference to maintain the connection.
if you are creating a new legal section, become familiar with related areas in order to avoid duplication and make appropriate use of cross-references.
add comments, especially those that reflect your own opinion or are necessary to explain the organizational choices you make. But try not to use comments as a substitute for material that would be more helpful if it were organized as topics and rules (or authorities). See Commenting.

A few tips:

Think about where a legal researcher will expect to find the legal information you are organizing, and create your organization to match those expectations.
Use topics liberally. This will help you to comply with the rule of seven [link above] and help keep the short text short [link above].
Avoid topics that don't tell you what the children are, that is, avoid topics labeled with the short text "Miscellaneous" and the like. Part of what makes Spindle efficient is that the researcher can figure out more or less what's inside a topic (what its descendants are) without clicking on it, which isn't possible with a catch-all topic. Keep working at it to find another way to organize.
Where the topic or rule seems to require more than seven children, subdivide in order to comply with the rule of seven: create a new child, which is logically the parent of two or more other children—usually a topic—and make it the parent of those children.

Add a New Topic, Rule, or Pollinator

Adding a Child With the Narrow Down Box

To add a child using the narrow down box

Start from the page for the topic, rule, or pollinator that you want as the parent of the new one. It will appear in bold in the Narrow Down menu box.
Click "add" at the bottom of the Narrow Down menu box.
An editing box will appear. Select the type of entry you are adding: a topic, split topic, rule, general rule, exception, or pollinator.
Select "short text," and type in the text. Please first review the discussion of the short text above.
Select "long text," and type in the text. Please first review the discussion of the long text above.
Choose "save" when you are done with the entry, or "cancel."

Using the Tree to Add Parents and Children

To add parents and children using the tree

Hover over the long text of any topic, rule, or pollinator and select "edit."
Choose "show tree" on the upper right corner of the editing box.
The editing box will appear where that topic, rule, or pollinator is positioned in the tree.
From here you can also click on any point in the tree to open the editing box in a new position and work from there. Click on the little plus signs on the left to expand branches.
Within the edit box, click "create new topic/rule." This creates a sibling.
Type in the short and long text.
Select the type of topic or rule icon.
Click "save." Or, click "cancel" to undo.
If appropriate, move the new topic, rule, or pollinator. See Using the Tree to Move Topics, Rules, and References
You can create and edit multiple branches before saving, but if you click "cancel" all changes will be lost.

Edit a Topic, Rule, or Pollinator, or Change What Type It Is

Edit Using the Narrow Down Box

To edit using the narrow down box

Browse to the topic or rule you want to edit.
Hover over the long text and select "edit."
An edit box will appear allowing you to edit the icon, the short text, or the long text.
Click on the appropriate fields and make your changes.
When you're finished choose "save." Or, to undo, click "cancel."
Your edit should not change the meaning of the topic, rule, or pollinator that already has authorities.
If you are editing a rule that has supporting authorities, your name and link to your profile will be shown as an editor of those authorities, and any gold vouches for those authorities will turn silver.

Edit Using Tree

To edit using the tree

Hover over the long text of any topic, rule, or pollinator and select "edit."
Choose "show tree" on the upper right corner of the editing box.
The editing box will appear where that topic, rule, or pollinator is positioned in the tree.
From here you can also click on any point in the tree to open the editing box in a new position and work from there. Click on the little plus signs on the left to expand branches.
Choose "short text" or "long text" to edit those, or the icon box to select topic, split topic, rule, general rule, exception, or pollinator.

Nominate a Topic, Rule, or Reference for Deletion

To nominate a topic, rule, or reference for deletion

Browse to the topic, rule, or pollinator that you think should be deleted.
Hover over the long text and click "nominate for delete" and "ok" (or "cancel" if you've changed your mind).
Click "add comment" to explain why you think it should be deleted.
If you change your mind, hover over the long text and choose "clear reject."
Branch managers will make deletions where the topic, rule, or reference is a duplicate or where there is no authority whatsoever supporting it.

Move Topics, Rules, and References Using the Tree

To move topics, rules, and references using the tree

Hover over the long text of any topic, rule, or reference, and select "edit."
Choose "show tree" on the upper right corner of the editing box.
The editing box will appear where that topic, rule, or pollinator is positioned in the tree.
From here you can also click on any point in the tree to open the editing box in a new position and work from there. Click on the little plus signs on the left to expand branches.
There are two ways to move the topic, rule, or reference to a different position in the tree:
- Drag & Drop:
  - Click on the up-down triangles.
  - Holding the cursor down, drag the topic, rule, or reference to the topic, rule, or reference you want as its parent until it is dark blue.
  - Release the cursor.
- Cut & Paste:
  - Click "cut & paste."
  - Click on the topic or rule you want to be the parent.
  - Click "paste." Click "cancel" to undo.
  - Click "save"
You can also use drag & drop or cut & paste to move a topic, rule, or reference to a different part of the tree altogether, including a different practice area.
To move a topic, rule, or reference up or down among other topics or rules at the same level (said another way, to change the order of siblings), click on the up or down arrows.
You cannot use the up/down arrows to change parent of the topic, rule, or reference, only to move it among its siblings.
You can also edit the type (topic, rule, reference) and short or long text from the edit box while in tree.
Note that if a topic or rule is part of a new law section being built behind the scenes, it will be "locked" and it cannot be moved or edited. That section will be out soon!

Create a Cross-Reference

To create a cross-reference

Browse to target of the cross-reference—that is, the place you want the researcher to leap to.
Click on the topic or rule to open the long text.
Hover over the long text and select "edit."
Choose "show tree" on the upper right corner of the editing box.
The editing box will appear in its position in the tree.
Click "create cross-reference."
A frog will appear.
Click on the text to edit it, if needed. (You can also edit the text as a later step.) This is the short text; there is no long text for cross-references.
Then select the home of the cross-reference by moving the cross-reference edit box.
Use either drag & drop (with the up and down arrow) or cut & paste (by clicking "cut & paste") (see above on moving topics and rules).
Note that a cross-reference goes only in one direction. If you want the cross-reference to work both ways, create a second cross-reference (perhaps as a child of the target of the first cross-reference, with the first cross-reference's parent as its target).