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] Proposal: Allow <xref> within <shortdesc>

Hi Rodolfo,

Keep in mind that for DITA 1.3 there will be an extremely simplified set of doctypes available for people who want to start with the minimum. We also provided a minimal doctype in DITA 1.2, but for topic only, and that doesn't seem to be getting much attention or use.

Generally speaking, the audience of the spec includes both specializers and authors, and most of the doctypes you see in DITA are constrained, and don't represent every possible option to the end user. A good example is the task type in DITA 1.2, which has a general version that can be used by specializers or authors requiring more flexibility, as well as a constrained version for use by most authors directly.

So when you say the standard is getting more complex every day, I need to understand which behaviors are triggering that reaction, since there are lots of different motivations on the TC.

- when we add two versions of a task, explicitly to accomodate direct users as well as specializers, are we making the standard too complex? We did it in an attempt to simplify things for end-users, but maybe we just made things worse?
- when we add more conref options, like range or push, for use directly by end-users, we're certainly making the standard more complex - but it's not because of a focus on specializers or implementers, it's directly in response to requests from advanced users. Which is where the simplified doctypes we're targetting for 1.3 come in, as an alternative for starter users or occasional authors.

In the example that triggered this discussion, does it really increase complexity for end-users if we let xref be authored directly in shortdesc, instead of making authors sneak it in wrapped in a ph? Making content models more consistent usuaally decreases complexity, rather than increases it, doesn't it? Unless there are really good reasons for guiding people down different paths with the different models, which I don't think is the case anymore on this issue.

Michael Priestley, Senior Technical Staff Member (STSM)
Total Information Experience (TIE) Technology Strategist

From:        "Rodolfo M. Raya" <rmraya@maxprograms.com>
To:        <dita@lists.oasis-open.org>,
Date:        09/11/2012 10:56 AM
Subject:        RE: [dita] Proposal: Allow <xref> within <shortdesc>
Sent by:        <dita@lists.oasis-open.org>

> -----Original Message-----
> From: dita@lists.oasis-open.org [
mailto:dita@lists.oasis-open.org] On
> Of Kristen James Eberlein
> Sent: Tuesday, September 11, 2012 10:59 AM
> To: Eliot Kimber
> Cc: dita
> Subject: Re: [dita] Proposal: Allow <xref> within <shortdesc>
> While I'd like to agree that our primary user group of concern is
> and "implementers," I think that for the DITA 1.x-level releases we have a
> responsibility to look out for other communities, including authors.

IMHO, making "specializers" and "implementers" the primary user group is a
mistake that leads to a standard that becomes more complex every day and
scares end users that want a simple solution for authoring documentation in
a structured manner.

I would prefer a standard that is easy to use right out of the box and
allows me to extend and customize if needed. DITA is going the opposite
direction offering too many options to the first time user.

I used to see DITA as  "start simple and grow as needed" but that's no
longer the case since the release of version 1.2.

Best regards,
Rodolfo M. Raya       rmraya@maxprograms.com

To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: dita-help@lists.oasis-open.org

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