nfoWorks: tools for document interoperability

d140605 nfoWorks devNote
RCT Profile Organization

Document Engineering


0.00 2017-06-14 20:22

{Ed.Note: Placeholder for Document Engineering.  For the moment, this is thinking outloud.}

  Beside the organization of RCT[1.0], there also needs to be document engineering that handles the versioning of the specification evolution and the progression between specific versions.  The top-level naming is for folder names that hold different versions.  This also creates a need for agreement on top-level folder names.  This seems to fit with the current nfoWorks (and nfoCentrale) approach for URLs to folders and then their default pages being includes to the "actual" material.

This approach is similar to the W3C approach to symmetrical linking of their specification stages.  There are fewer "approval" stages here, because the governance and consensus practice is simpler.

We will start out major versioning immediately.  That is, there is RCT 1.0, to be followed by subsequent editions (e.g., "RCT 1.0 (Second Edition)") and also subsequent versions (RCT 1.1, etc.)..

To manage the organization, it looks like there will be rct/, rct1.0/ and then rct1.0-yyyymmdd-var/ where var is something like WDnn (Working Draft), SDnn (Specification Draft), SPnn (Specification), and perhaps PRnn (Profile).  Those nn's might run progressively, and it is how there is gathering into the rctm.n/ folders and also then rct/ that makes the difference.  rct/ might be an umbrella for the rctm.n/ set, as well.  It is also possible to dispense with the nn, since the dates are differentiators.  So these things might be in the titles but not in the folder names.  (I am leaning to have the additional structure in the names so they can distingished that way in a list of folders.)

The next issue has to do with the granularity of these documents.  For the W3C, a specification is a single HTML page.  There's no subpage structure.  For nfoWorks, authoring of sections is by use of design-time include pages.  This will raise issues around cross-referencing among sections that are so-developed.  There are some experiments to run to determine whether or not this is feasible.  It is also desirable that relative references in the resulting inclusions remain relative to the combined container and do not leap to the included source.   It is also clear that a systematic fragment-identifier structure is needed.  This is a bit brittle, and doesn't allow for renaming and renumbering of sections and subsections very well.

Some experiments are necessary to determine what will work with transclusions of portions of a page.  How that works out will also determine how it can work when a specification has more than one web page.   In that respect, having the folders of those pages carry the top-level versioning is quite handy, so the pages within folders can have similar names and maybe some uplevel relative referencing will work for cross-references within multiiple pages of a single specification hypertext.

Hamilton, Dennis E.
RCT Profile Organization Document Engineering.   nfoWorks devNote page d140605d 0.00 July 12, 2014.  Accessed at <>.
Revision History:
0.00 2014-07-12-11:17  Initial Placeholder
Provide initial placeholder content ready for further expansion.

Construction Structure (Hard Hat Area)
Creative Commons License You are navigating nfoWorks.
This work is licensed under a
Creative Commons Attribution 2.5 License.

created 2014-07-12-11:17 -0700 (pdt)
$$Author: Orcmid $
$$Date: 17-06-14 20:22 $
$$Revision: 18 $