RE: [dita] *Where* to document how to build subsets of the DITA 1.2 specification

["Stan Doherty" <stan@modularwriting.com>]

Hi --

Relative to previous releases of spec source material, what we have in DITA 1.2 is more complex and ambitious. Without instructions from us about what will and will not build in a default DITA-OT installation and which maps build what, the casual DITA reader will have a bad and frustrating experience.

I am OK with the idea that we ship source WITHOUT build instructions IF we point readers explicitly in the DITA spec to a specific location (DITA-OT? Adoption TC?) where they can get build instructions. 

I just do not want to sit through more user group meetings and conference workshops in which DITA competitors and critics make claims that DITA is so complex or convoluted that it is unusable ... and in our case, unbuildable by mere mortals. Let's defuse that criticism before it gathers any steam. You folks have done such a fabulous job with the spec ... ensuring that readers can go somewhere to get instructions on how to build it is important.

Thanx,
Stan

Stan Doherty
Director, Technical Publications
Verivue Inc.
Westford MA
sdoherty@verivue.com


-----Original Message-----
From: "Bruce Nevin " [bnevin@cisco.com]
Date: 02/18/2010 09:24 AM
To: "Gershon Joseph (gerjosep)" <gerjosep@cisco.com>, "Kristen James Eberlein" , "Stan Doherty"
CC: dita@lists.oasis-open.org
Subject: RE: [dita] *Where* to document how to build subsets of the DITA 1.2 specification

I agree, not in the spec. Here's the picture that comes to my mind. A readme.txt in the zip archive makes good sense, if OK with OASIS, in combination with documentation placed on dita.xml.org that can contain more detail and examples. The readme points to the resource page for a more readable and more detailed presentation; the doc on the web mentions the readme as a reminder that is always handy even when offline since it comes in the zip. My 2 Λεπτά.

/Bruce

> -----Original Message-----
> From: Gershon Joseph (gerjosep)
> Sent: Thursday, February 18, 2010 5:08 AM
> To: Kristen James Eberlein; Stan Doherty
> Cc: dita@lists.oasis-open.org
> Subject: RE: [dita] *Where* to document how to build subsets
> of the DITA 1.2 specification
>
> I vote for the DITA focus area and/or the Open Toolkit. I
> don't think this belongs in the spec at all.
>
> My 2 Agarot worth (a little bit more than 1c at the current exchange
> rate...)
>
>
> --
> Gershon
>
> -----Original Message-----
> From: Kristen James Eberlein [mailto:kris@eberleinconsulting.com]
> Sent: Tuesday, February 16, 2010 7:47 PM
> To: Stan Doherty
> Cc: dita@lists.oasis-open.org
> Subject: [dita] *Where* to document how to build subsets of
> the DITA 1.2 specification
>
> Let's remember that we also could use dita.xml.org to
> distribute "How to" information about building subsets of the
> DITA 1.2 spec ...
>
> This gives us the following current options:
>
> * DITA 1.2 specification (in a non-normative appendix)
> * Documentation for DITA Open Toolkit (requires agreement
> by Toolkit
> folks)
> * Resource page on dita.xml.org
>
> I also do have an open e-mail to Mary McRae asking about
> other alternative possibilities; could we have a readme.txt
> file in the ZIP file for the source documentation, for example?
>
> Best,
>
> Kris
>
> Kristen James Eberlein
> Principal consultant, Eberlein Consulting Secretary, OASIS
> DITA Technical Committee Charter member, OASIS DITA Adoption
> Committee www.eberleinconsulting.com
> +1 919 682-2290; keberlein (skype)
>
> ---------------------------------------------------------------------
> 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_workgr
> oups.php
>
>
> ---------------------------------------------------------------------
> 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_workgr
> oups.php
>
>