EOOXML project lessons learned

From Grokdoc

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 objections page. For that purpose, please use the comments/corrections thread on the Groklaw publication of that that page's text. See also the EOOXML Objections Clearinghouse page for ongoing efforts to document Ecma 376 problems.

• Please use new sections for new major topics.

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 (click the "discussion" tab at the top of the 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 not a new edit session) 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.
• Don't edit elsewhere, then save as a new edit session. Wikis assume that when you start a new edit session, that you started with the text it sent. Admins of MediaWiki-based sites might want to edit the page MediaWiki:Copyrightwarning to include this text (which is displayed in every edit): "DO NOT copy the text elsewhere, edit it, start a new editing session, and paste that edited text back into the new editing session. Starting a new editing session this way can erase other people's work."
• 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.

Control who can edit

Unfortunately, there are malicious people who are paid to prevent user freedom, and there are also many well-meaning but uninformed people. When there's a deadline to create a document, it may be useful to limit document editing to a group of people known to be helpful and informed, at least just before the deadline (and perhaps throughout the editing process). WikiMedia's Group Based Access Control could be used to limit who can edit a particular page to such people. One idea would be to let a larger group edit at first, and then shut it down to a smaller group afterwards.

Prepare for the next time now

Waiting until the next time there is a need for a similar project to create a system for it is too late. Bringing the project together quickly without appropriate systems in place and tested caused a helter-skelter collision of people working without adequate software, without definition of roles and responsibilities, and without sufficient guidance as to workflows. A systems-based approach to preparing for the next time should be taken, now.