Whim

DocBook As SpecBook?

My e-mail to experts at Adobe and Sun (on the OASIS Technical Committee for ebXML), as well as my posting to the docbook-apps listserv:
http://lists.oasis-open.org/archives/docbook-apps/200401/msg00301.html
===================
Fwd: [docbook-apps] DocBook for authoring Technical Requirements, Specifications?
From: William Reilly
To: mxxxx@ adobe.com, dxxxxxxxxxx@ Sun.com

Hello, Matt MacKenzie & Doug Bunting,

I'm very interested in (possibly) using DocBook not to "Doc"ument but to
Specify a system.

Looking for a "SpecBook," or "ReqBook" ;^) essentially.

Or, to learn that DocBook itself might be a good choice...

--- WHY I'M WRITING YOU ------------------
From the DocBook WIKI I learned that:
"OASIS ebXML Message Services TC has decided to use DocBook for version 3.x
of its specification"
http://www.docbook.org/wiki/moin.cgi/WhoUsesDocBook

I then found your names from this OASIS page:
http://www.oasis-open.org/committees/documents.php?wg_abbrev=ebxml-msg

Looks like V2 Spec. "formatting was based upon the Internet Society's Standard
RFC format, converted to Microsoft Word 2000."
http://www.oasis-open.org/committees/ebxml-msg/documents/ebMS_v2_0rev_c.pdf

And I found the ebXML DTD and XML used in Oct. 2002:
http://www.oasis-open.org/committees/ebxml-msg/documents/requirements.xml
http://www.oasis-open.org/committees/ebxml-msg/documents/requirements.dtd

--- MY BASIC QUESTION -----------------
My question would be a wide open one:
- Are you using DocBook to write requirements, or specifications?
- How is that going?
- Have you needed to extend DocBook (to get your "reqDetails" kind of tags,
etc.)?

Any info, comments, or sample files you feel you could share would be most
welcome.

I'm at a not-for-profit educational organization, http://www.cast.org -
creating improved online test-taking for learning-impaired and print-disabled
kids.

--- THANK YOU -----------------
Many thanks for your time...
Best regards,
William Reilly
william@ reilly2001.info
Somerville, Massachusetts
http://reilly2001.info
=========================
P.S. This page (WhatIsDocBookUsedFor) lists everything _except_ specifying
systems!)
As I note (below, in my post to docbook-apps mailing list):
"Perhaps it's that the overhead of authoring in a markup language is seen
as detrimental to the shorter life of these "upstream" documents, as compared
to downstream documentation efforts, which ought to endure long after a
system is built and in use."
http://www.docbook.org/wiki/moin.cgi/WhatIsDocBookUsedFor
---------------------------------------------
# help systems
# Web sites
# books
# reference pages
# FAQs
# white papers
# training courseware
# articles
# API documentation
# reports
# functional specifications
# "how to" guides and other procedural documentation
# presentations
---------------------------------------------
---------- Forwarded Message ----------

Subject: [docbook-apps] DocBook for authoring Technical Requirements,
Specifications?
Date: Thursday 29 January 2004 11:47
From: William Reilly
To: docbook-apps@lists.oasis-open.org

Greetings.

Searching Google, OASIS, and "Requirements" community sites hasn't yet shown
me whether there are XML vocabularies generally in use for creating system
requirements and technical specifications documents.

DocBook occurred to me, despite its having been designed to "doc"ument a
system more than specify one.

Any "SpecBook" or "ReqBook" out there?

Or is going the MS-Word or OpenOffice .DOC template route the only way these
days? (or Rational ReqPro, LiveSpecs, and similar expensive commercial
products)

Perhaps it's that the overhead of authoring in a markup language is seen as
detrimental to the shorter life of these "upstream" documents, as compared to
downstream documentation efforts, which ought to endure long after a system
is built and in use.

Many thanks for suggestions, comments.
William Reilly
Somerville, Massachusetts, U.S.A.
william@reilly2001.info

To unsubscribe from this list, send a post to
docbook-apps-unsubscribe@lists.oasis-open.org, or visit
http://www.oasis-open.org/mlmanage/.

-------------------------------------------------------

FINALLY:
Dave Pawson was kind enough to respond with:

You might try .gov sites?
I guess they are still into full requirement specs etc?
Perhaps mix it with iso9000 and stuff as part of the search?

HTH DaveP
(ex mil.std :-)
==========================

XML Editors: Cladonia Exchanger vs. SyncRO oXygen

I wanted an inexpensive XML Editor IDE for Linux (ideally for Windows and as plug-in to Eclipse, and doubly ideally for one license price).

DISCLAIMER: Below, I've written not a review, but taken some semi-organized notes.

If anyone reading has comments, questions, clarifications, I would definitely like to hear about all.

Minor UPDATE in "Comments" below... [Feb. 13, 2004]

Cladonia Exchanger, v. 1.2 is $98, or $45 non-profit
SyncRO oXygenXML, v. 3.0 is $74, or $48 non-profit.
One license lets you install to Linux or Windows; oXygen can also work as Eclipse plug-in.

Click on the two screenshots below to see full-screen.

Exchanger

oXygen

30-day trials, more screenshots at:
http://www.cladonia.com
http://www.oxygenxml.com

(One more I've not (yet) looked into is MyEclipseIDE.)

Conclusion First:
Well, if I really had to buy right now, I think Cladonia's Exchanger would provide me more useful functionality than oXygen, but, there are as always some tradeoffs.

Read the first few bullets under "NOT SO GOOD, COMPARISON" and "GOOD COMPARISON" for each product below to get the gist pretty quickly.

I know it's always kind of deadening to go through such a lot of info.
Briefest High Level Points:
-=-=-=-=-=-=-=-=-=-
Exchanger is stronger in XPath; Schema viewing; and keeping main and outline views in synch (something I rank high). It also has some interesting other "services" (SOAP. SVG, etc. details below).
But - Exchanger cannot work too well with DTDs directly (I was disappointed). To get context-sensitive dropdown of valid elements (something I rank high), you can't use a DTD but must convert it to either a Schema or to the Exchanger proprietary concept of "named Type." Kind of odd; ah well.

oXygen creates v. nice HTML doc for your Schema; can work better with DTDs; can work as Eclipse plug-in; has better U/I generally.
-=-=-=-=-=-=-=-=-=-

N O T E S

==================
Cladonia Exchanger = $45 (non-profit; $98 reg.)
(Like oXygen, one license per user, not OS. Buy once and run on Linux, Windows. Nice.)
==================

GOOD, COMPARISON

MAJOR
- XPath
Superior in Exchanger. Larger textarea box, for starters (more of the long Paths visible), but more importantly, clicking around in either the document or the outline keeps that XPath textarea updated. This is good. (XML Spy only lets you "calculate XPath" when you enter its modal dialog devoted to that. Exchanger's is nicer in that it's integrated into working with the document.)
oXygen has just about no automatic connection to the XPath textarea.
Both do have a dropdown button for "memory" of reusable recently executed XPaths.
- "Schema" View
Pretty interesting: you open not the Schema per se, but an XML document, and ask for the view of the Schema document it's using. (You can then ask for the Schema of the Schema...). Provides good navigation among "Globals," "Refers," and "Substitutions". Useful. (And yes, if you want, you can always simply open a Schema as a file, but this mechanism lets you skip that.)
Generally, it's fair to say that Exchanger Schema support (viewing, esp.) is far superior to Oygen. The latter provides typical text view of the .XSD document, and the usual Outline available in side pane. But Exchanger provides far more (as described just above).
(Do note that Oxygen can produce nice HTML documentation of your Schema, but right in the IDE is kind of hard to beat.) Also, note that although Oxygen has an attractive "Tree Editor," that doesn't really bring anything esp. useful to looking at an .XSD.
On the other hand, Oxygen does offer a nice button to get a browser-link, re: XSD, out to the W3C Spec, for any validation errors encountered in your XSD (e.g. auto connect to URLs like: http://www.w3.org/TR/xmlschema-1/#src-resolve ).
One more important note: Apparently the Exchanger "Schema Viewer" is also a FREE stand-alone product (they call it "service") offering: http://www.cladonia.com/schemaviewer/ (v. 0.5)

- Synchronizing between Outline and Main Edit works both ways (click and it synchs other pane).
- Outline is a little less elegant looking, but the fact you can, in Preferences, turn on "Show Attributes" means that the Outline in Exchanger can be much more useful than its counterpart in oXygen, where it's more attractive at a glance (elegant, narrower), but as it doesn't carry any attribute info, you are presented with a long list of "unlabelled," as it were, elements. (e.g. Exchanger shows: 'chunk id="passage4"' on top of 'chunk id="passage5"' and so on, while oXygen shows: 'chunk' on top of 'chunk' on top of 'chunk' and so on. You get the idea.)

- Also important to note are Exchanger's XQuery 1.0 and XSLT 2.0 support, though I'm not using these things.

MINOR
- Exchanger has "Viewer" view, which complements the "Editor" view, by providing the '+/-' sign convention for collapse/expand (as seen in IE presenting raw XML). oXygen lacks this, and you realize its value when you have large areas of XML to range over, and it's nice to be able to "move" some out of the way like this.
- Outline has handy "Collapse All" and "Expand All" buttons.
- Search Again (F3) does NOT synchronize between Main and Outline.
- The "Format" (indent) button took care of removing all the hard linebreaks that were in the book.xml document. This could be quite useful in certain situations...

GOOD, SINGULAR
MAJOR
- Has "Go to Start Tag" and "Go to End Tag" buttons. Useful.
MINOR
- Has immediate, top of right-click menu, Find (word cursor's on)
- Has "Select Element Content" and "Select Element" buttons. Useful.
- Has "Convert Characters to Entities", "Convert Entities to Characters", and "Strip Tags from Selection" buttons. Interesting, sometimes useful, I suppose.

NOT SO GOOD, COMPARISON

MAJOR
- Cannot use DTD for context-sensitive elements
(offers auto-convert to Schema, or "Type")
- Looking at a DTD only works in "Editor" mode; no color-coding even. (Exchanger requires well-formed XML to do much else (e.g. "Viewer" mode, Outline, etc.). This is fair (oXygen too shows DTDs simply as text file, though you do get color-coding).)
(For careful reading of DTDs, use LiveDTD or DTDParse anyway - converters to useful hyperlinked HTML.
http://www.sagehill.net/livedtd/
http://sourceforge.net/projects/dtdparse/ (Whoops, my Perl modules lacking; sorry.)
/home/william/bin/livedtd-run
file:///home/william/schemata/dtd/ims_qtiasiv1p2p1/index.html
- Doesn't work/plugin to Eclipse
- No nifty "Schema Documentation" like Oxygen has.

MINOR
- Not getting Line Numbers (?) (though Preferences says I can set them. Hmmmm.)
( I submitted a Bug to SourceForge )
UPDATE: If you turn off "Soft Wrap Lines," then Line Numbers will work. They're working on making Line Numbers work regardless... (Nice responsive next-day e-mail to bug report :^)
- Doesn't provide "EOF/EOL" visible markers
- Bottom pane can't go away, and it's shortest height is too high
- Nothing re: "webdav" nor "ftp" in Help Search. Hmmm.
- Cannot 'Ctrl' click multiple files open (not a v. big deal)
- No "Close All Files" (not a big deal)

OTHER
- Also important to note (things I've not looked into): "Services" like SOAP; PIMnet; SVG; XHTML; Java Conduit. See: http://xngr.org/services.htm

- A "real" review (Oct. 2002) is at: http://www.nwfusion.com/newsletters/web/2002/01590348.html.

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

==================
OxygenXML = $48 (non-profit; $74 reg.)
(Like Exchanger, one license per user, not OS. Buy once and run on Linux, Windows, & Eclipse. Nice.)
==================

GOOD, COMPARISON

MAJOR
- CAN use DTD for context-sensitive elements
In fact, can even provide you context-sensitive elements list dropdown with NO schema, dtd, relaxng. How? It has a "Learn Structure" feature which automatically kicks in to provide you this editing assist. Quite nice. (It's also supposed to have a "Save Structure" to create a new file, but, this was not working for me.)
- DOES work/plugin to Eclipse
- Wow. "Schema Documenter" produces a beautiful, information-rich HTML page of your XSD, including (collapsible) "Schema Component Representation" and "XML Instance Representation" (code snippets).
- DOES provide "EOF/EOL" visible markers

MINOR
- CAN 'Ctrl' click multiple files open
- Has "Open File at Cursor" e.g., if there's a filename or URI in your file, put the cursor on it, right-click, and this opens that file. Nice.
- WebDAV and FTP features

GOOD, SINGULAR
- Tree Editor. Quite nice, separate app (separate window). Exchanger has an "Outliner" which (in the same IDE) permits some "editing/writing without messing with tags" like this oXygen Tree Editor does, but the Tree Editor is far more impressive, far more mature.

NOT SO GOOD, COMPARISON
MAJOR
- XPath use not as good as Exchanger (details above).
- Schema viewing not as good as Exchanger (details above).
- Does NOT synchronize between Outline and Main Edit both ways - only one: click in Outline to get synched in Main Edit. Would be nice to click in Main and get Outline to synch. Ah well.
- Outline is more elegant looking, but less useful. (See note above under Exchanger.)

MINOR
- No "Viewer" view (as in Exchanger) ('+/-' sign convention for collapse/expand (as seen in IE presenting raw XML).The utility in this is when you have large areas of XML to range over, and it's nice to be able to "move" some out of the way like this. Ah well; in oXygen you just cursor up and down all the XML in plain text editor kind of mode.
- Outline does NOT have handy "Collapse All" and "Expand All" buttons.
- Search Again (F3) does NOT synchronize between Main and Outline.
- Left pane can't go away, and it's shortest width is too wide.
- Did NOT remove all the hard linebreaks that were in the book.xml document. (The "Format" (indent) button)
Maybe you could make the case it shouldn't, but, I still think this could be quite useful in certain situations...

==============
BOTH
==============

COMPARABLE - NOT SO GOOD
- Not a show-stopper, but neither have the nice visuals for XML Schema as found in more focussed (and more expensive) products like Tibco ($270) (formerly extensibility) Turbo XML (visual = http://www.tibco.com/images/solutions/products/extensibility/schema_editing_screenshot.gif) or Altova's (Windows only) XML Spy ($400) (visual = http://www.xmlspy.com/images/shots/schema_view_tree.gif) [They have a "Home" version for $50 that does get you the XML Schema editor :^), but no XPath, no XSLT debugger, and many other things not :^( ]
[News (to me): If you want Windows on Linux, go to CodeWeavers.com and for $60 get CrossOver Office. Then you can run XML Spy on Linux. Hmmmph.]

COMPARABLE - O.K.
- Transformation Scenarios. Look to be pretty comparable. Exchange has XQuery; Oxygen I think doesn't. Oxygen lets you append a header or footer (from a URI) to your transform output.
- Converting Schemata. At a high level, both seem to offer a lot vis-a-vis Converting Schemata, one type to another. Exchanger also has concept of named "Types," which permits even more along these lines. Oxygen tells us it's using James Clark's Trang; don't know about Exchanger. (as with so much of this, you'll have to see the documentation, website, or product to understand more. sorry...)
- Both have "Find All" or "Find in Files," which put clickable links to all occurrences of word in a 2nd pane. oXygen has somewhat better context provided (line text, file, and line/col number). Exchanger 2nd panel info not quite as elegant context provided (line; file (full path; can be good, can be too verbose), and line (no col) number).
Exchanger makes this feature available only if you create a Project. (In both products, it's not available if you're searching on one file only (then you just get hit highlight, with F3 to "find again.")
Exchanger 2nd panel info not quite as elegant context provided (line; file (full path; can be good, can be too verbose), and line (no col) number).

MINOR
- Both have buggy Java (Swing?) menubar dropdowns that don't permit another application's window to which you change the focus, to paint over the dropdown. You have to go back to Exchange or oXygen and click somewhere else to close the dropdown, then you can go back to your other window.
- Presentation of error messages on validation are comparable, but I think I prefer Exchange's (oXygen's is a bit slicker, ease of getting about in them, but you have to click more to read full message. Exchange's plainer, fuller, right there. A matter of taste, etc.)
- Presentation of Find In Files uses same pane and functionality. In this case I find I prefer oXygen's better controls; Exchanger lacks even a horizontal scrollbar to read overly wide info, or resizable columns.

JobSearch Update E-Mail Blast

Back to our story.
The economy must be expanding a bit, because a developer left CAST for a new programming job, opening up a slot they needed to fill, which is where I come in.

ASIDE:
Hmmm. Confirmation of a trend. Case of the same story reported in yesterday's newspaper (!):
Boston Globe, Jan. 19, 2004. "FOR TECH FIRMS, RECOVERY BUT NO '90S REPLAY"
'..."Here's a surprise: A programmer who worked for us just took a job at another company," said Paul Egerman, chairman and chief executive at eScription Corp., a Needham firm that makes speech recognition software for doctors. "That hasn't happened in years." ...'

Below, brief descriptions of:
- COMPANY
- POSITION
- PROJECT
- HOW THEY FOUND ME
- TECHIE BIT

And that's all the news that fits.

Thanks for your time in checking out this JobSearch Update of mine.
You can also see it online in my weblog at:
http://www.reilly2001.info/whim/archives/jobsearch/jobsearch_update_email_blast_2004-01-20.html

Best wishes for the (still somewhat) New Year.
William
william@reilly2001.info
http://reilly2001.info
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-----------------
COMPANY
http://www.cast.org
CAST "...is a not-for-profit organization that uses technology to expand opportunities for all people, especially those with disabilities."
- Education, online learning, assessment (web accessibility, text-to-speech,
screen readers, and more).
- Funding from various gov't., education, and industry sources.
- Wakefield, Massachusetts. Founded 1984.

----------------
POSITION
3 months project as an XML developer (XSLT, Schema, Apache Cocoon, Cocoon-Forms) along with some Java. (See "Techie Bit" below for details.)
- They do like to have/keep long-term contractors.
- There's potential for employee hire later.

--------------
PROJECT
- The goal is to improve the accessibility of online assessments (tests, quizzes) for learning-impaired, blind, and otherwise print-disabled students.
- To begin, the result will be implemented in Rhode Island schools this year.
- Interesting stuff.

-------------------------------------
HOW THEY FOUND ME
The hiring manager typed into Google:
"resume Massachusetts Cocoon"
and I came up twice within the first 6 hits. Good thing about having a weblog. (And about working on a still somewhat arcane (and distinctively named) technology.)

--------------------
TECHIE BIT
I don't know a lot yet (start tomorrow), but Cocoon's approach to forms handling will be central to this interface. That's been called "Woody" and now "Cocoon-Forms."
http://wiki.cocoondev.org/Wiki.jsp?page=Woody
It differs from W3C XForms :^(, but quips and quotes from those in the know on listservs seems to indicate you can't go too far wrong tackling Cocoon's version for now, and see what happens in the world of XForms down the road...

From the world of online education, the Digital Talking Book and the QTI (Question-Test-Interoperability) DTDs are key to all this,
- ANSI/NISO Z39.86 Digital Talking Book
http://www.loc.gov/nls/niso/
- IMS QTI Question & Test Interoperability
http://www.imsproject.org/question/index.html
as well as the use of XML Schema for other "local" data aspects (as I thus far understand it).

Also, Cocoon's Actions and/or Flowscript will be central to controlling the application's screens and user interaction.
http://wiki.cocoondev.org/Wiki.jsp?page=Flow

Finally, enough Java to properly handle 1) some custom Cocoon 'generator's, possibly, and 2) capturing and re-presenting the student's data (responses, profile, etc.), plus 3) tracking and measuring the clickstream, with some of these things going to a MySQL database.
My best guess for the moment. I'll put up news (as permitted) on my weblog, http://reilly2001.info/whim/.

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Thanks again for reading, and, send me an e-mail to say Hello if you like.
(Or, even better, enter a Comment here in the weblog!)
Best,
William
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=