Discussion: OIC TC Specification Analysis

Context

Specification Analysis (discussed on this page)

Dependencies

There are currently no identified dependencies between this material and other activities and materials. -- orcmid 2009-03-17 18:23:06

Discussion Topics

1. Experimental Explosion of ODF 1.1 onto the OIC TC Wiki

There is now enough experimental content to provide an appraisal of what it takes to build a specification analysis. There are these main conclusions:

2. Labor-Intensive Creation. Creating the Specification Analysis is necessarily labor intensive.
3. Off-line Workflow. Off-line editing and use of SVN expedite creation and maintenance of the Specification Analysis.
4. Manual Synchronization. It requires special care to synchronize and maintain consistent content between the off-line content and the separately-changeable live Wiki content.
5. Multi-Level Documentation. There is need for documentation so that working with the material requires the least amount of expertise appropriate to the situation.
6. Tying-In OIC Content. The appropriate bridging from specification through discussion to agreed analysis and OIC guidance needs careful attention to ensure that OASIS Technical Committee Procedures are honored.

RECOMMENDATION: My personal recommendation is that this work be continued with accelerated transcription of more sections of the ODF 1.1 specification. It is also time to start discussion some of the material that is there and seeing how that works. -- orcmid 2009-06-17 00:34:06

MAINTENANCE-IMPOSED DELAYS: The value of authoring via SVN-managed pages was vindicated in one respect recently. When the wiki was upgraded using an automatic wiki version 1.6 upgrader, considerable breakage occured as the result of incorrect upgrader actions. The SVN-maintained sources provided a reliable way to synchronize with the changes, analyze the breakage, and introduce manual repairs to restore the content. On the down side, restoration was a significant manual activity that required great care. This remains the best way to accomplish the Specification Analysis on an OASIS authorized site, despite the fact that Wiki-based collaborative-authoring may never be very appealing for this material, considering the care required to preserve the structure and style. -- orcmid 2009-12-20 23:13:44

2. Labor-Intensive Creation

It is easy to "turn-the-crank" using copy-and-paste to move content of the ODF 1.1 Specification to Wiki pages. There remains significant manual effort.

There are appropriate wikiText idioms for transcription of the individual specification headings, text paragraphs, lists, tables, images, and schema fragments.
These seem to work well. The current sparse skeleton illustrates all of these cases.
It is possible to set up the specification extracts so that there is easy flow between the individual Wiki pages that express the ODF 1.1 specification as a hypertext document. This structure also facilitates linking from other materials including commentary by others as well as those produced as part of the OIC work.
The current specification scaffolding and skeletal content illustrate these cases.
The selection of appropriate chunks and organization into the hypertext structure is a predominately manual activity.
Although one can envision manual tools to assist with this work, starting with XML parts of the ODF Specifications ODT package, there remains considerable need for manual guidance and customization of the process.
The current manual workflow provides a structure where increased automation can be experimented with at will.
Although it requires trained editors to accomplish the extraction of the ODF specification, that can be done by a single individual. The discussion and analysis may be more interesting with regard to the interests of the OIC TC participants.
Critical Limitation: There is no procedure to simply take a specification document and transform it into a specification analysis of the kind constructed here.
The current manually-preserved and manually-connected structure is brittle to the extent that structural changes required careful rework.
This approach is unsuitable for use with specification drafts and documents still subject to reorganization, change of section numbers, and so on. This is an important consideration in any anticipatory OIC work involving new versions of ODF specifications produced in advance of approval as OASIS Standard.

3. Off-Line Workflow

It is extremely tedious to create wikiText and edit the Specification Analysis Wiki pages using the browser form provided with the MoinMoin wiki implementation.
When initial work was peformed entirely using browser access, the process was extremely error-prone and it was difficult to maintain context. Being paced by the MoinMoin editing time-out was also an irritant.
Current procedures allow any flexible text editor to be used in making the wikiText content off-line from the OIC Wiki.
Any desktop-computer or workstation text editor capable of making UTF8 text with lines of indefinite length can be used. Editor provisions for soft line-wrapping and indentation are particularly helpful. It is valuable to have soft line wraps easily distinguished from hard line breaks.
This particular page is being edited with jEdit 4.3pre16, an open-source editor implemented in Java. Editors used as part of programming Integrated Development Environments (IDEs) and light-weight standalone editors are all usable, so long as the need for arbitrary long lines with no automatic hard line breaks can be satisfied. (Paragraphs such as this one consist of a single line of wikiText. It is desirable to have an easy way to create and review such text with shorter lines that do not involve true line breaks.)
SVN Integration is Natural. The off-line editing is done in Working Copies of a section of the OIC Subversion (SVN) repository. This provides backup preservation of the work and allows for collaborative use of the material.
Copies of the SVN form of the Specification Analysis can be downloaded by anyone who sets up a Subversion client for that purpose. All of the SVN repository is open for organized download.
OIC TC members can collaborate in off-line development and maintenance of the material using Subversion for managing coordinated introduction of changes from multiple contributors.
Off-Line development also allows for manual use of page templates and boilerplate. There can be additional organizational content as well.
Change-history, annotation of the development activity, and other additional activities become possible.
It is also possible to take advantage of the fact that the SVN repository is a web site.
The efficiencies of off-line workflow impose additional requirements for experties of those who maintain coordinated development of the Specification Analysis wiki off-line and on-line.
This added complexity does not impact those who simply want to add text to non-specification content using the browser interface. Additions can be made to existing discussion, analysis, and supporting pages by anyone who is fluent enough with the browser interface and the wikiText format being used.
An even easier way to add comments without particular expertise in working with the wiki is to submit comments to an appropriate OIC TC list and allow an editor to move the comments to the wiki structure.
The main impact is on those editors who want to maintain structural information and also keep the wikiText materials synchronized between the SVN repository and the Wiki.

4. Manual Synchronization

An important limitation of the off-line workflow process is that SVN coordination does not extend to the "live" Wiki pages themselves.

The Wiki pages may be edited independently by any OIC TC member who desires to record a comment, make modifications and additions, or any other change.
If a Wiki maintainer posts an SVN-managed update to a Wiki page, any changes made directly to that page since the last SVN-managed update will be lost.
Currently, it is necessary to manually check whether there are changes to a Wiki page before it is selected for editing by pasting a new SVN-managed page to the Wiki.
When a manual check reveals that there are direct changes on the Wiki, it is necessary to merge those changes with the SVN-managed changes and then bring the complete merged page to the Wiki as an update.
This merger is a manual activity at present.
There are software tools that help in determining the differences between the Wiki page and the latest SVN-managed page. These can simplify merging direct Wiki changes back to the SVN-managed page.
Available procedures and tools for merging pages have not been attempted at this point. There is a sandbox where this can be done via safe experiments. That needs to be done before we have the first update collision to deal with. -- orcmid 2009-06-17 02:12:10
Important Safety Factor. Although it is possible to move SVN-managed content to the Wiki and "paste over" changes that have been made separately, those changes are not lost.
It is possible to go into the wiki history and find the page with the direct changes. Those changes can still be integrated with the more-recent SVN-managed addition.

5. Multi-Level Documentation

There does need to be documentation of how the Wiki and the SVN are used to create and maintain the Specification Analysis.
The Working with Specification Analysis outline is designed to provide progressive disclosure of increasingly-specialized information.
I propose to complete the first three topics first, so that observers of this work can contribute to it. -- orcmid 2009-06-17 02:37:16
The first three topics are
The fourth topic, Participate in Specification Analysis Discussions, is for OIC TC members who want to add discussion directly to the Specification Analysis Wiki. The remaining topics involve more-specialized contribution. These can be completed as the main Specification Analysis continues to be populated.
The documentation of the most-specialized cases is done so that anyone else could take over the maintenance of the Specification Analysis Wiki. It is also useful for someone interested in creation of a different Specification Analysis for an OASIS TC or in another setting. (Implementation Notes can benefit from versions of specification and test-guidance hypertexts, for example.)

6. Tying-In OIC Content

The easiest way to tie the Specification Analysis to OIC-delivered OASIS content is in three tiers: specification, discussion, and analysis/guidance.

The specification. This is no problem for presentation on the Wiki. The ODF Specification explicitly permits this kind of use. There are only two precautions:
The expansion of ODF specifications in the Specification Analysis Wiki is never the definitive/authoritative source. If there is any question, the main source should always be consulted. Also, if a discrepancy is noted, it will be corrected at once when brought to our attention.
There is no mixing of discussion and analysis on pages that contain extracts for the hypertext of the specification. All discussion and analysis are on other Wiki pages (or elsewhere) and not on the same pages as the extracts from the specification.
There is linking to discussion and other supporting materials from the specification hypertext, but that is all. Other materials cross-reference back to the specification hypertext using provisions designed to encourage that usage. Confusion about which is which is carefully avoided.
Discussion. The discussion pages are not OIC work product in any way. They are for arbitrary discussion. Any contributions and expressions of opinion are not in any way conclusions of the OIC TC.
The idea is that discussion is just like wiki typical Wiki-based discussions. The only difference is that posting of discussion is limited to member of the OIC TC and rules of contribution apply as described on the FrontPage of the OIC Wiki.
Reminder: The OASIS IPR Policy and other OASIS rules apply to these pages and posting to the Specification Analysis Wiki. These materials are not stable artifacts and the discussion pages, in particular, are subject to arbitrary editing by contributors and editors.
Analysis/Guidance. This is where the situation becomes tricky. Analysis and Guidance that is produced as an approved result of the OIC TC is subject to strong requirements for preservation in stable form and retention in an an appropriate location and form.
This is generally in material that is published as documents and possibly digital compilations that are retained and accessible as a single collective work. It may also have several layers of organization and detail (e.g., test assertions, test definitions, test documents might be in a hierarchical expansion).
Any version on the wiki (or elsewhere in hypertext form) is probably not to be taken as the authoritative form, although it might be keyed to an authoritative form in a way that the authoritative version can be accessed and verified.
Ideally, such content in hypertext form is in an on-line location that is not editable in Wiki fashion. One possibility might be pages of the Subversion repository that have stable locations and can be linked from the Specificaton Analysis Wiki materials. Those page might even be in HTML and be accessible as addiitional hypertext.
Ideally, approved analysis/guidance hypertext could be maintained in a read-only state, protecting against inadvertent alteration. The material could also be versioned, making location of replacements and updates convenient.
All of this is yet to be worked out. However it is done, there must be honoring of the OASIS Technical Committee Procedures and other requirements for the official work of the OIC TC. -- orcmid 2009-06-17 04:50:52

This page is maintained as SpecAnalysis-discussion.txt in the SpecAnalysis folder of the OIC SVN repository.
- See also: Construction of the Specification Analysis Wiki and OIC SVN SpecAnalysis Construction Material.