EOOXML project lessons learned
From Grokdoc
| Revision as of 19:06, 24 January 2007 Stevenj (Talk | contribs) (→Avoid edit conflicts) ← Previous diff |
Revision as of 19:11, 24 January 2007 Stevenj (Talk | contribs) (→Purpose of this page) Next diff → |
||
| Line 10: | Line 10: | ||
| * Please be careful to use section break markup for every section. That's four consecutive hyphens at the beginning of a line immediately followed by a new line. The section break markup goes at the bottom of a section. (The absence or mangling of the section break markup was one of the problems encountered in the drafting project that led to lost edits.) | * Please be careful to use section break markup for every section. That's four consecutive hyphens at the beginning of a line immediately followed by a new line. The section break markup goes at the bottom of a section. (The absence or mangling of the section break markup was one of the problems encountered in the drafting project that led to lost edits.) | ||
| - | **This is incorrect: <nowiki>----</nowiki> is the wiki for a horizontal rule, not a "section break". If you want a horizontal rule before each section (sections begin with <nowiki>==Section Title==</nowiki>), the correct thing to do is to use a style sheet that specifies this. Then there would be no confusing and nonstandard (compared to other MediaWiki wikis) "manual" formatting rules. | + | **This is incorrect: <nowiki>----</nowiki> is the wiki for a horizontal rule, not a "section break". If you want a horizontal rule before each section (sections begin with <nowiki>==Section Title==</nowiki>), the correct thing to do is to use a style sheet that specifies this. Then there would be no confusing and nonstandard (compared to other MediaWiki wikis) "manual" formatting rules. (In any case, horizontal rules could be added in a sequence of one-second individual edits to each section, and are no excuse for lost edits.) |
| * Other? ??? | * Other? ??? | ||
Revision as of 19:11, 24 January 2007
Contents |
Purpose of this page
Let's build a page here that can serve as guidance for future collaborative Groklaw document drafting efforts that need to be completed in a very short time. The basic suggested guidance for building this page (and please feel free to edit this section):
- This page is for future guidance, not discussion of problems we encountered. Use this page's talk page or the Groklaw Lessons Learned thread for such discussions.
- Use this page's talk page to discuss what information should be on this page.
- Neither this page nor its Talk page are for corrections to the text of the EOOXML Issues page. For that purpose, please Use the comments/corrections thread on the Groklaw publication of that that page's text. ???NeedLink.
- Please be careful to use section break markup for every section. That's four consecutive hyphens at the beginning of a line immediately followed by a new line. The section break markup goes at the bottom of a section. (The absence or mangling of the section break markup was one of the problems encountered in the drafting project that led to lost edits.)
- This is incorrect: ---- is the wiki for a horizontal rule, not a "section break". If you want a horizontal rule before each section (sections begin with ==Section Title==), the correct thing to do is to use a style sheet that specifies this. Then there would be no confusing and nonstandard (compared to other MediaWiki wikis) "manual" formatting rules. (In any case, horizontal rules could be added in a sequence of one-second individual edits to each section, and are no excuse for lost edits.)
- Other? ???
Start with Structure
Starting with a skeleton structure of topics or problem areas was key. The nature of Wiki editing is that it is easy to add content in a particular place, or to refine a given section into subsections. But it is difficult to do wholesale movements of content from one section to another
Communicate with other editors
A wiki involves the efforts of many people, so editing it is not like editing a document you write yourself. To promote cooperation, you should take advantage of the wiki's facilities to communicate with other editors:
- Use edit comments for non-trivial edits to explain what the edit is doing. If your edit is too big and complicated to be summarized by a short edit comment, then you should probably split it into multiple edits (this is also important to avoid conflicts, as described below).
- Use the Talk page to:
- Propose major changes (involving changes to many sections) before they happen.
- Discuss major objections to the document, before deleting someone else's efforts.
- Propose tentative additions, things you aren't sure of but may be incorporated once they are refined.
- Work out disagreements with other editors.
- Notify other editors of upcoming lockdowns and so on.
Avoid edit conflicts
Wikis often involve simultaneous editing by many people, and the MediaWiki software used by Grokdoc has only limited capabilities for merging simultaneous changes. If you aren't careful, you can accidentally revert other people's hard work by committing changes to an obsolete version of the document. To minimize these edit conflicts, obey the following guidelines whenever possible:
- Use many small edits, rather than a few major edits. The longer you spend editing the document without saving your changes, the greater the chance of an edit conflict.
- Edit individual sections or subsections whenever possible, as opposed to editing the whole document or a large section at once. There is no conflict if two editors work on disjoint sections simultaneously. If you need to edit several sections, consider breaking your edit up into several smaller edits.
- Make multi-section edits quickly: if you do have to edit multiple sections at once, for example to move a section from one place to another or to do a global search-and-replace, do it quickly and don't mix it with other edits. This will minimize the probability of a conflict.
- For example, if you want to move a section from one place to another, it should take only a few seconds.
- To do a global search-and-replace should also take only a few seconds: open the page for editing, copy to another editor that supports search-and-replace, do the replace, then paste back (to the same window) and save.
- Don't ignore edit conflict warnings. If you do have an edit conflict, the MediaWiki software should warn you. Don't ignore this and paste over your changes; use the history to see what has changed and merge it in, or make your changes again to the latest version if they are quick.
- As a last resort, request that an admin lock the page temporarily. And, of course, discuss such a major change in Talk.
Adding content
Usage of the Discussion Page
Notes and fragments of items to be added, not deemed major at that time should be added in the Discussion Pages. After gathering a few similar items, these fragments can represent significant areas of discussion, warranting an addition into the main page.
Deletion of content
Consensus
It would be good if the editor were to cross check sections to be deleted with discussions at the Talk pages to see if other contributors have had substantial deliberations on the issues first. If the editor thinks the section should be deleted even after the consensus was to include the section, then a short justification in the Talk pages would help.
Section deletes
The editor should not delete large areas of the documents in one go. If possible, the editor should delete it section by section to allow the change tracking to correctly reflect the areas deleted.
