OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] TractorX Example


Hi,

To summarise:

1. Can linguistic complexities realistically be handled by programatic or mathematical combinations?

2. If this happens to work for one language, does it work for all?

3. If minimalism requires an in-depth, fundamental understanding of both product and end-user, this combined with linguistic complexities can offer novel solutions.

4. The current key mechanism already offers multiple layers of abstraction, that can inform those novel solutions.

For consistency reasons, a company decides to abstract the product name to a reuse, product related topic.

Then it becomes an OEM manufacturer, and now the product names are all re-branded, multiple times.

Where is the source for the product name abstraction? A product related topic, or a brand related topic?

Actually, both. Abstract first to the product related topic, and then to the brand related topic.

HTH,
David


> Hi folks,
> 
> Firstly, apologies for coming late to the party.
> 
> I assume that behind this example is a desire to produce documentation for both individual products and either a group or a kit of products?
> 
> Is that really so difficult that it requires a totally new mechanism - scoped keys?
> 
> An individual owner wants to know about their specific purchase - the oil for their tractor.
> 
> A service centre needs to know about the oil for each tractor.
> 
> Hypothetically, the service centre has a choice. To buy the best oil grade in bulk and use for all tractors, or to stock each different oil grade. A buying and logistics headache, sure. But this is important to know for the documentation - whether to advise bulk purchase of one grade, or list all variants.
> 
> If bulk purchase, then each document variant only ever needs to be concerned about a single type of oil. An abstracted phrase, keyword, or term element.
> 
> If a list of all possibilities, then the individual documents just list one type of oil, and the service centre document contains all choices. Careful content design and an abstracted list or table.
> 
> In other words, is the all tractor document an OR combination or AND combination? It would certainly be wrong to assume that a combined service document is simply an amalgam of individual documents. Some content could require an OR combination, other content could require an AND combination.
> 
> Obviously, you would want to reuse content from individual tractor content for the combination. But that's not difficult with conkeyref redirection from specific content to generic content. An empty element with @id and @conkeyref. There need be no content duplication. To put another way: double abstraction from rendered topic to generic topic to specific topic.
> 
> Another example, from a gratuitously patronising Welcome topic(!): "Thank you for your purchase of .... what?"
> 
> Individual product documents:
> 
> ... the Massey Ferguson LoadLugger tractor
> ... the Massey Ferguson SpeedShoveller tractor
> 
> Combined product document:
> 
> ... the Massey Ferguson Xtreme series.
> 
> (Caveat: I have no links to Massey Ferguson, and the products are made up!)
> 
> OK, that works for English. But what happens when it is translated, in particular into, say, Polish, Russian or Finnish. Does the architectural mechanism of an abstracted phrase still work?
> 
> With a good understanding of the subject matter, i.e. minimalism, and careful content design, I think it should be possible to accomplish a great deal with the current key mechanisms.
> 
> I'm concerned that scoped keys could be a step too far for software manufacturers and DITA users, some of whom appear to be struggling with the 1.2 keys.
> 
> Many apologies if I've not understood the arguments or business case correctly, or if I'm being a party pooper!
> 
> BTW, I was one of a number of folk who spoke at the last DITA Europe conference about key mechanisms.
> 
> Many thanks,
> David
> 
> 
> On 9 Apr 2013, at 17:28, Chris Nitchie wrote:
> 
>> I want to try and tease out the hypothetical Eliot brought up during the TC
>> call today. Imagine, today, you had two DITA maps for different tractor
>> models, TractorX.ditamap and TractorY.ditamap. There also exists a third
>> map,  AllTractors.ditamap, that included both TractorX and TractorY. Because
>> we live in a DITA 1.2 world, where a given root map has exactly one key
>> space, we’ve prefixed all of our keys with their context. This allows one of
>> the TractorY topics to reference a key in the TractorX map.
>> 
>> TractorX.ditamap
>> ----------------
>> <map>
>> <title>Tractor X</title>
>> <topicref id="x1"
>>           keys="TractorX.OilChart"
>>           href="TractorX/oilChart.dita"/>
>> <topicref keys="TractorX.RegularMaintenance"
>>           id="x2"
>>           href="TractorX/regularMaintenance.dita"/>
>> </map>
>> 
>> TractorY.ditamap
>> ----------------
>> <map>
>> <title>Tractor Y</title>
>> <topicref id="y1"
>>           keys="TractorY.OilChart"
>>           href="TractorY/oilChart.dita"/>
>> <topicref id="y2"
>>           keys="TractorY.RegularMaintenance"
>>           href="TractorY/RegularMaintenance.dita"/>
>> </map>
>> 
>> AllTractors.ditamap
>> -----------------------
>> <map>
>> <title>All Tractors</title>
>> <mapref href="TractorX.ditamap"/>
>> <mapref href="TractorY.ditamap"/>
>> </map>
>> 
>> TractorY/RegularMaintenance.dita
>> --------------------------------
>> <topic id="topic">
>> <title>Regular Maintenance</title>
>> <body>
>>   <p>Refer to <xref keyref="TractorX.RegularMaintenance"/>,
>>      using <xref keyref="TractorY.OilChart"/> for the oil
>>      chart.</p>
>> </body>
>> </topic>
>> 
>> EFFECTIVE KEY SPACE FOR AllTractors.ditamap
>> -------------------------------------------
>> TractorX.OilChart=x1
>> TractorX.RegularMaintenance=x2
>> TractorY.OilChart=y1
>> TractorY.RegularMaintenance=y2
>> 
>> 
>> So DITA 1.3 comes out with the scoped keys feature as currently described in
>> 13004. The author of AllTractors.ditamap introduces them (for reasons I
>> don't quite understand).
>> 
>> AllTractors.ditamap with Scopes
>> -------------------------------
>> <map>
>> <title>All Tractors</title>
>> <mapref href="TractorX.ditamap"
>>         keyscope="tractor-x"/>
>> <mapref href="TractorY.ditamap"
>>         keyscope="tractor-y"/>
>> </map>
>> 
>> This turns the single key space into three key spaces.
>> 
>> ROOT KEY SPACE
>> --------------
>> tractor-x.TractorX.OilChart=x1
>> tractor-x.TractorX.RegularMaintenance=x2
>> tractor-y.TractorY.OilChart=y1
>> tractor-y.TractorY.RegularMaintenance=y2
>> 
>> TRACTOR X KEY SPACE
>> -------------------
>> (inherited from root)
>> tractor-x.TractorX.OilChart=x1
>> tractor-x.TractorX.RegularMaintenance=x2
>> tractor-y.TractorY.OilChart=y1
>> tractor-y.TractorY.RegularMaintenance=y2
>> (scoped key names)
>> TractorX.OilChart=x1
>> TractorX.RegularMaintenance=x2
>> 
>> TRACTOR Y KEY SPACE
>> -------------------
>> (inherited from root)
>> tractor-x.TractorX.OilChart=x1
>> tractor-x.TractorX.RegularMaintenance=x2
>> tractor-y.TractorY.OilChart=y1
>> tractor-y.TractorY.RegularMaintenance=y2
>> (scoped key names)
>> TractorY.OilChart=y1
>> TractorY.RegularMaintenance=y2
>> 
>> 
>> The problem here, as Eliot points out, is that the reference to
>> TractorX.OilChart from TractorY/RegularMainenance.dita will no longer
>> resolve, because that key is no longer defined in Tractor Y's key space.
>> However, the reference to TractorY.OilChart will continue to work just fine,
>> as will any other reference to a TractorY key from within a TractorY key
>> scope.
>> 
>> The author now has a number of ways to fix the problem.
>> 
>> * Change the key reference to "tractor-x.TractorX.RegularMaintenance".
>> * Add a new <keydef> to TractorY.ditamap for "TractorX.RegularMaintenance".
>> * Add a new <keydef> to AllTractors.ditamap for
>> "TractorX.RegularMaintenance" (which would override the definition in the
>> tractor-x scope, but would make the key visible to all child scopes).
>> 
>> Chris
>> 
>> 
>> Chris Nitchie
>> Oberon Technologies, Inc.
>> 2640 Wildwood Trail
>> Saline, MI  48176
>> Main: 734.666.0400 Ext. 503
>> Direct: 734.330.2978
>> Email: chris.nitchie@oberontech.com
>> www.oberontech.com
>> 
>> 
>> 
>> 
>> 
>> ---------------------------------------------------------------------
>> To unsubscribe from this mail list, you must leave the OASIS TC that
>> generates this mail.  Follow this link to all your TCs in OASIS at:
>> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>> 
> 

Attachment: smime.p7s
Description: S/MIME cryptographic signature



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]