Re: [dita-lightweight-dita] Full DITA compatibility

["Noz Urbina" <noz.urbina@urbinaconsulting.com>]

I seem to have confused things by saying 'sections'. My point was if you
do away with <section> (the element) then users will need to use topics to
divide up their content into 'sections' (the things). Therefore, <topic> =
section, because it becomes the element used to logically section up the
content into blocks. <section> just goes away. Hence at one point I meant
<topic> but said section.

> So I'd suggest that, if possible, we steer clear of using non-specialized
> sections for arbitrary titled chunks in Lightweight DITA.

I agree with this completely.

About your heading/nav issue, Joe, I think that the map could easily be
used as the default and the @chunk attribute used for overrides to tell
processors where to add headings in navigation. If the map points to it,
it goes in the nav. If it's nested in the topic, then it doesn't, unless
some clever person overrides it with a @chunk. There's a lot of simplicity
benefit in just having map=nav in a 1-1 relationship.

Unless we no longer require titles, then I keep getting stuck on the
creative workflow problem of creating something that you don't know is
going to be a topic/section/headed-block until long after you've created
it. As a marketing user myself, I would not be able to author into a
system where I had to know where all the section and topic boundaries were
before I started writing. In a major global operation with embedded
processes and content models, it might fly, but that's a huge barrier to
adoption and isn't maturity-model friendly. In small projects/less
organised or mature teams/small companies, they will be authoring against
a looser model and need to be able to put a heading around a few
paragraphs retrospectively without having to jump through hoops to repair
my topic/section hierarchy.

I think this cuts to the core of what we're trying to accomplish and some
DITA design goals. One of the reasons topics only nest at the bottom so
that you can't do things like:

<topic>
stuff
  <topic>
  stuff
  </topic>
stuff
  <topic>
  stuff
  </topic>
stuff
</topic>

If you pulled out the two subtopics, the parent topic would most likely be
a mess, with 'holes' in the words. Aka, we've allowed a 'bad topic' to get
created. In DITA today, we're using structural validation to
encourage/enforce good modularity in the created content. I think we might
have to back off that and make it 'their problem'.

It's a cost benefit analysis which I think most mass-market users would
jump on in a new york second. Today folks want and do reuse but there just
are no supporting mechanisms or automation support. So, they spend endless
hours running around updating things and fixing contextual issues (modular
writing problems).

With LDITA, they will have reuse support from conrefs/maps/keys, and they
will have far *fewer* contextual writing issues to chase down because at
least be making an effort (as opposed to making nearly zero effort
previously). But yes, they will still have to be careful because not all
topics are equal*. Some will have somewhat more limited re-usability. They
will still be a massive, massive step forward.

What about having a way to require a title for creator-use only? e.g., You
can have a title-less topic, but if so, you need to give it some sort of
description line so that it can appear in searches, allowing you and your
colleagues to know what that loose content actually is.

I liked this article a lot, which discusses this for HTML5
(http://www.brucelawson.co.uk/2010/html5-articles-and-sections-whats-the-difference/).
In it there was an example would map perfectly to a <topic>/<section>
world, but in a <topic>/<topic> model, then the topic without it's
subtopics would not be a sensible topic, and topics aren't nesting at the
bottom*. I think that's something we can safely leave as "their problem".

<article>
<h1>Important legal stuff</h1>

<section>
<h2>Carrots</h2>
<p>Thingie thingie lah lah</p>
</section>

<section>
<h2>Parsnips</h2>
<p>Thingie thingie lah lah</p>
</section>

<section>
<h2>A turnip for the books</h2>
<p>Thingie thingie lah lah</p>
</section>

<strong>Vital caveat about the information above!</strong>
</article>

Michael, I think the use cases put forward make sense for why titles might
need to be optional**, what is the argument for making them required?

Noz

* Today we have topics that just hold libraries of warnings, or topics
that are just a title to contain other topics... these are "less reusable"
topics.
** I haven't mentioned IDs because the average user doesn't care or know
about IDs today except for the first few weeks of DITA use, where they
configure their editors to auto-ID everything they might ever want to
reuse.


On Mon, May 11, 2015 10:36 am, Joe Pairman wrote:
> I'd add to that — <section> in DITA isn't intended to be a nestable,
> navigable unit as many people would assume from the name "section". It's
> not nestable and in the default processing, section titles aren't
> displayed in navigation. It's really intended for specialized containers
> *within* a unit of navigation, such as the examples that Mark gave.
>
> It might sound odd, but if users want arbitrarily nestable, navigable
> units that are contained in a single storage object, nested topics are a
> better fit. More on this from conversations on DITA-Users regarding
> Jarno's Markdown DITA plugin:
>
> https://groups.yahoo.com/neo/groups/dita-users/conversations/messages/36903
>
> https://groups.yahoo.com/neo/groups/dita-users/conversations/messages/36928
>
> So I'd suggest that, if possible, we steer clear of using non-specialized
> sections for arbitrary titled chunks in Lightweight DITA.
>
> Just my 2p.
>
> Joe
> ________________________________________
> From: dita-lightweight-dita@lists.oasis-open.org
> <dita-lightweight-dita@lists.oasis-open.org> on behalf of Mark Poston
> <mark.poston@mekon.com>
> Sent: Monday, May 11, 2015 9:12 AM
> To: Noz Urbina; Michael Priestley
> Cc: Fredrik Geers; dita-lightweight-dita@lists.oasis-open.org
> Subject: Re: [dita-lightweight-dita] Full DITA compatibility
>
> Not sure I agree with that statement. Sections are also very useful to
> break content up into more semantic groupings that do not necessarily need
> a title. A title might be implied by the name of the specialised tag, and
> not actually require the title element itself. It is then down to the
> delivery stylesheet to decide whether a title is displayed or not.
>
> <prereq>, <context> etc. in a task are examples of this.
>
>
>
> On 11/05/2015 08:20, "Noz Urbina" <noz.urbina@urbinaconsulting.com> wrote:
>
>>The entire point of a section would be to have a heading.
> ---------------------------------------------------------------------
> 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
>
>


-- 
Noz Urbina
Content Strategist and Founder, UrbinaConsulting.com

Author, "Content Strategy: Connecting the dots between, business, brand,
and benefits" http://thecontentstrategybook.com