Re: Links that are both local and cross-deliverable in shared topics


Chris Papademetrious
 

Hi Eliot,

The bug with Oxygen is when option #2 is used ((1) the current book A has its own local scope A, and (2) it references a peer book B with scope B, and (3) you drag-and-drop a topic from map B into a topic in map A to create a cross-book link), the link is incorrectly created as "B.B.topic1" instead of "B.topic1". SyncroSoft has confirmed it's a bug.

It would be hard to separate writers from their maps here. Each technical writer is assigned 1-3 products, and they own the user guides and reference manuals for those products. Because the map controls both PDF and OLH content delivery, the writers work with maps as tightly as they do the topics.

So, I try to empower the writers to manage their own maps by

  • Keeping map structures and rules as simple as possible
  • Using Schematron rules to keep writers on the right path
  • Relying on Oxygen to make things like cross-book link creation easy
So far, this combination has allowed us to be successful without the need for map/key managers and such, and without the writers having to get too much into the technical DITA stuff. For the most part, it's just writing and Oxygen GUI stuff. And I'll ride that for as long as I can! (And quite frankly, we're not resourced for anything more.)

We're already using peer-book scopes, so local scopes should be a straightforward conceptual extension for the writers to learn. Once this double-scoping bug is fixed in Oxygen, we should be in good shape for creating cross-book links in topics reused across books, which is really cool.

The next hurdle is creating cross-book links between books that use profiling conditions to publish one map to multiple deliverables. Writers want the ability to cross-link to specific conditional versions of books, and also to cross-link automatically between same-condition books. I've had some success prototyping this with a "wrapper map," which is a simple <map> that has only a <ditavalref> and a <mapref> to a full <bookmap>. I plan to share more about that here when the loose ends are ironed out.

The tip about books being able to provide overriding key definitions is a good one - thank you!

 - Chris

Join main@dita-users.groups.io to automatically receive all group messages.