Fwd: Re: Packaging etc

On Fri, Jun 12, 2015 at 4:43 PM, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

I think we should prototype this both ways and assess the usability.

Main page with links to the three parts (assuming that we could have a line explaining what the part is); each of the three parts has a cover pages.

Main page with links to the three editions; links lead directly to the first topic in the edition. In this case, we'd add a topic to the map before the "Introduction to DITA" section; the topic would explain the edition.

Chet, just checking that #1 with the brief sentences explaining the parts in the "Additional artifacts" section is OK?

As always, many thanks for your help.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)

On 6/12/2015 4:28 PM, Chet Ensign wrote:

No, the links under Add'l arts would point to wherever you want each of the editions to begin. You would likely have the links repeated in the body of this top level introductory document e.g. where you explain in more depth what each of them does and who it is for, etc. But someone clicking on the link for the Technical Edition is going to go right to the first document in the Technical Edition tree.

We will need to discuss those starting pages. Using this model, they can't be OASIS cover pages like the main one. In this approach, they'll have to be structured more like a chapter. E.g.

1. DITA Base Edition

The DITA Base Edition is for users who need etc etc . A complete download of this Edition can be downloaded at <url>.

Have a look at the spread sheet again. I have mapped out the file structure under this approach.

On Fri, Jun 12, 2015 at 4:10 PM, Nancy Harrison <nharrison@infobridge-solutions.com> wrote:

So, just to clarify my understanding, the links under the 'Additional Artifacts' section don't point to the cover pages for each edition, they point to somewhere else in the overview, which then points to cover pages for the individual editions?

Nancy

_____________
Nancy Harrison
Infobridge Solutions
nharrison@infobridge-solutions.com

On Fri, Jun 12, 2015 at 12:27 PM, Chet Ensign <chet.ensign@oasis-open.org> wrote:

Ok, the attached is a mock up of how this could work in practice. This would be your front page for DITA V1.3 just like the example I pointed you to last night for PLCS (http://docs.oasis-open.org/plcs/plcslib/v1.0/plcslib-v1.0.html). Note that now, under Additional artifacts, you have DITA V1.3 Base Edition (link), etc. I'll go with one short sentence in that reference to identify the audience. That link then navigates you down into the body to the starting point for each of those subtrees.

Yes, this still has to be a document with a TOC and body copy again like the PLCS document. You can use it for orientation, etc. I think the diagrams need to go in that body as well. Yes, HTML, PDF and editable source will be required *for that document*. What you have below that is up to you. If there is only HTML in the descendent documents (as is the case for PLCS), that is ok.

We can talk about the details of text, urls, etc. here but the bottom line is that I think this gets you closer to what you want. It certainly eliminates "Part".

Let me know what you think.

/chet

On Thu, Jun 11, 2015 at 7:29 PM, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

I am so totally waiting on Nancy and Tom's expertise to build us a prototype. Go team!

Thanks, Chet.

Kris

Sent from my iPad

On Jun 11, 2015, at 6:46 PM, Chet Ensign <chet.ensign@oasis-open.org> wrote:

Have a look at Product Life Cycle Support Version 1.0 (http://docs.oasis-open.org/plcs/plcslib/v1.0/plcslib-v1.0.html) and ignore the frames.

This is an HTML, PDF and editable source document in front of the most mammoth collection of auto-generated HTML files you want to see in your life time. In fact, take a peek at the directories and files.

It is *not* multi-part. It is all kinds of stuff auto-generated from their source package.

So - what I am suggesting you think about is one front page - HTML, PDF and editable source - that acts pretty much like Part 0 Overview in our current conversation - but then takes people to stand-alone trees of content with your editions. Each edition has a its spec documentation, its associated files, and stands alone.

So - you get one front page that meets OASIS requirements, that leads readers naturally down to the edition they want, which themselves are individual trees and thus content that people can download and use or bookmark or whatever.

And they are not parts of a multipart work, so the hideous "Part" word goes away. And it is one DITA V1.3 spec, so OASIS process is happy.

Before you ask, the top page must still (as PLCS does) follow the OASIS model - you can describe the thing in the Abstract which, with Additional artifacts gone and skipping Related work can be right after the Editors. And yes, as in PLCS, there will have to be some copy after a TOC.

But it gives you (1) one landing page, (2) no "Part" words, (3) a pathway directly to your three subtrees.

Have a look and give it some thought...

On Thu, Jun 11, 2015 at 6:25 PM, chet.ensign <chet.ensign@oasis-open.org> wrote:

I have another idea. working on dinner at the moment. but this might be the solution. I'll send email with the description later this evening

Sent from my Verizon Wireless 4G LTE Smartphone

-------- Original message --------

From: Tom Magliery

Date:06/11/2015 6:14 PM (GMT-05:00)

To: Kristen James Eberlein , Chet Ensign

Cc: Nancy Harrison , Robert Anderson , Michael Priestley

Subject: RE: Packaging etc

Kris,

I completely agree, but I don't think you meant to say "they are not standalone pieces". Clearly they are -- just exactly as much as a home/business/enterprise edition of some software would be.

mag

From: Kristen James Eberlein [mailto:kris@eberleinconsulting.com]
Sent: Thursday, June 11, 2015 2:52 PM
To: Chet Ensign
Cc: Tom Magliery; Nancy Harrison; Robert Anderson; Michael Priestley
Subject: Re: Packaging etc

We don't want to publish these separately. They are not stand-alone pieces. The base is the central part of both technical content and all-inclusive, and all-inclusive cannot work without technical content.

Think of this as a software release. Some people opt for the distribution with the smallest foot print; some need the medium- sized business edition, and other need the enterprise edition with everything in it but the kitchen sink.

For DITA , I suspect that we will rearchitect stuff so that the packages canbe more standalone, but we cannot do so now and maintain backward compatibility.

Kris

Sent from my iPad

On Jun 11, 2015, at 5:21 PM, Chet Ensign <chet.ensign@oasis-open.org> wrote:

Hi all -

Ok, I am going through these now. Please understand that I'm not trying to be arbitrary. I am trying to enable you to get DITA V1.3 published in a form that meets your preferences *and* meets the requirements that I am charged with ensuring, as spelled out in https://www.oasis-open.org/policies-guidelines/tc-process#specQuality and in http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#URIs-Resources

If you want these editions to be truly stand-alone entities with their own individual names, high-level root addresses and not have the word "Part" in their title, why not re-consider publishing them as separate CSDs. We can explain and point from one to another using the Related work section of the cover page, the abstract and of course in the body of the content. Yes, it does of course mean separate public reviews, separate approval votes and the like but it avoids what you don't like about how we publish multi-part specifications.

By the way, do you plan to put a Conformance section in each of the parts? Or just one with the all-inclusive? The latter approach should be ok given that you've said the all-in piece is intended mainly for product vendors. But it occurred to me this p.m. as I was looking at the organization...

For now though, on these...

On Thu, Jun 11, 2015 at 4:56 AM, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

Based on our communications with Chet, here is what I think OASIS requires -- Chet, please check this out ASAP and ensure that it conforms to OASIS requirements, especially in regard to wording:

Part 0: Overview of the DITA 1.3 specification

Delivered in HTML, PDF, and DITA source (which ideally would be for the whole darn thing: Parts 0-3 -- But, Chet, let us know whether we need to have it be be just of part 0)

Maybe I don't get how the DITA source is supposed to work. First, the requirement for HTML, PDF and some kind of editable source is from the TC process link above.

Have a look at the spread sheet I sent yesterday again. I assumed that each of your editions has its own separate DITA source. Are these somehow filtered out of some complete package of source content so that someone looking at part 2 technical content is just looking at DITA through some style sheet filter?

For Part 0, all I picture is three files that live in docs.oasis-open.org/dita/dita/v1.3/csd01/part0-overview/. One is HTML, one is PDF and one is some sort of editable source. The document would be similar to the 1.1 example - the OASIS-maintained metadata cover and the TC authored content in the body of the document after the TOC. There wouldn't be anything else in the directory, certainly not the whole darn thing.

Contains standard OASIS cover page info + TOC for "1.0 Introduction to DITA"

Important: The standard OASIS cover page info MUST have detailed information about why we are delivering parts 1-3; what they are, etc. HIGH UP on the page.

Whatever information goes on that front page must fit in format that every other specification at OASIS uses. The sequence of fields that you see on every spec is the sequence that DITA must follow. I will work with you on placing more info in the Additional artifacts or the Abstract or etc.

Part 1: Base edition of the DITA 1.3 specification

For Part 1, I picture a complete collection of content for a reader to read and use, starting from

--

/chet
----------------
Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

--

/chet
----------------
Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

--

/chet
----------------
Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

/chet
----------------
Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

dita message