Affected Ditamaps Panel

[jmorales]

To help manage reuse, and promote communication between writers, it would be awesome if Oxygen XML Author could include an "Affected Ditamaps Panel." For whatever topic is currently open in the editing pane, this panel would instantly list all ditamaps that use that topic, directly or indirectly, and also list the author name from the metadata for each ditamap.

I am aware of the Resource Hierarchy/Dependencies feature, but with our department having 36,000 topics and dozens of writers, that feature is much too slow to be useful. It seems like there needs to be a background process that maintains an index. You need one anyway for refactoring links when topics are moved or renamed, because currently that process is also way too slow.

Thanks for listening. Hopefully you are already thinking of something along these lines.

[Radu]

Hi,

Thanks for the feedback, we already have an internal issue to create some kind of internal cache of DITA dependencies and use it in multiple places (when moving resources or when computing dependencies). I added your feedback on the issue. We plan to release Oxygen 23.1 in March this year but maybe we'll have more time to look into this for Oxygen 24 (Autumn 2021). We'll update this forum thread when an improvement becomes available.

By the way, in Oxygen 23.1 the computation of the DITA references graph used for move/rename will be a little bit faster.

Regards,
Radu

[jmorales]

Thanks, Radu! That's very encouraging. I appreciate all your efforts.

[Radu]

Hi,

One more thing which may help you, only if you are using Oxygen 23.0 in the main menu Help->"Install new add-ons" if you use our default add-on update site there is a free add-on named "DITA References View". If you install it, the add-on contribute a "DITA References" side view with both "Incoming" and "Outgoing" references. The graph for the "Incoming" references is computed only once per Oxygen startup and is reused to present references when you edit multiple topics so you will only need to use the Refresh button in the "Incoming" tab when you consider that the current information is stale.

Regards,
Radu

[jmorales]

Thanks Radu, I just tested the DITA References view in 23.1. The Incoming tab shows almost exactly what I was looking for. This is awesome and will make it so much easier to manage our interdependencies! Thank you.

It would be better still if the DITA References view could provide a way to quickly expand the entire tree view or all the references nested within a particular branch. The behavior could be similar to the Expand All / Collapse All features in the DITA Maps Manager pane.

Thanks again!

[sorin_carbunaru]

Hello,

Just wanted to let you know that I created an improvement request (EXM-48556) related to expanding branches in DITA Reusable Components.

All the best wishes,
Sorin Carbunaru
Oxygen XML Editor

[jmorales]

Thanks, Sorin!

[jmorales]

Thanks, Sorin. Here's a related new feature request. In the DITA References pane, it would be very useful if I could copy the contents of that pane, so I could paste it to a text file or spreadsheet for planning purposes. Now, I can imagine a complication for the design, which is how to render the fact that some of the lines of text are nested in a tree structure. I think you could just include tab characters at the start of each copied line to indicate the level of nesting.

Thank you for considering this suggestion. I just spent hours collecting this type of information, and the feature I mention would have made it a lot easier.

[Radu]

Hi,

Thanks for the improvement suggestion, I added an internal issue for it. Do you want the report to be for the "Incoming" or "Outgoing" links?
In a perfect scenario for you, would you like to have such a report for each topic in your project? Something like an overview of the linking state in the project?

At some point I experimented with creating linking graphs from DITA Maps, like for example this is the linking graph for the Oxygen XML Blog:
https://blog.oxygenxml.com/resources/sa ... hBlog.html
And here's how it's done:
https://blog.oxygenxml.com/topics/creat ... _maps.html

Regards,
Radu

[jmorales]

Thanks Radu. My interest is in the incoming links. The link graphs are interesting and we might get use out of them at some point. However, my immediate use case was rather different. There was a name change for one of our products, so I did a search to identify all the topics and components that referred to that product. Then from that list, I wanted to identify all the ditamaps that use any of the affected topics, so I could notify the writers who are responsible for those documents. This was a project that took me many hours to accomplish.

In my ideal world, the output from Find/Replace in Files feature could include a list of the parent ditamaps for any topics/components that are returned by the search. However, it seemed like a lot to ask for, so I made my request a bit more narrow. I thought, if I can just open each topic from the Find results, look at the incoming links, and manually copy that info off to another file, that would at least have been faster than what I actually had to do. So I sent you that feature request.

In reality, I had to use Open/Find Resource to query which ditamaps made use of each topic, because the Open/Find Resource pane allows me to copy the results. Unfortunately, there were some cases where we had topics with the same filename (though in different folders), so the Open/Find Resource pane sometimes gave me references to some ditamaps that were parents of a different topic with the same filename. It took awhile to manually weed those out later.

In general, in our group, writers are owners of whole documents rather than individual topics, so to find the affected writers, we constantly have to track down which ditamap is used by a topic. The Incoming tab in the DITA References pane works great for that if you're only interested in tracking down the parent ditamaps for a single topic. But it a case like this, where I had identified hundreds of topics that need a change, and I needed to locate the parent ditamaps for all those topics, it was a comparatively tedious process. This is not an everyday task, but it is one that I expect to recur occasionally. Hopefully you can keep this kind of scenario in mind as you plan possible future enhancements. Thanks for all your help and understanding.

[Radu]

Hi,

Thanks for taking the time to discuss your use case in more details. I added your comments on the opened internal issue.
In time as the product complexity increases and the array of products grows in a company the work of a technical documentation writer ends up being similar to the one of a software engineer, managing complexity, trying to reuse as much as possible, trying to understand what product manuals change when a certain modification is propagated and I agree we need to provide you with the tools to do this easier.

Regards,
Radu

[chrispitude]

Hi jmorales,

Going off on a tangent... If you have access to a linux environment, I have a perl script that takes a list of .dita/image/etc. files as input, then returns all the .ditamap files that reference them anywhere in their hierarchy.

For example, here I give it some wildcarded topics from a warehouse directory, and it tells me which books use them:

Code: Select all

$ get_affected_root_maps.pl dita/_warehouse/common_intro/*.dita
dita/gui_ug.ditamap
dita/frontend_ug.ditamap
dita/scripting_ug.ditamap

The script also accepts a list of files from stdin, so you could pipe a file of file names into it:

Code: Select all

$ ls -1 dita/_warehouse/common_intro/*.dita > files.txt
$ cat files.txt | get_affected_root_maps.pl
dita/gui_ug.ditamap
dita/frontend_ug.ditamap
dita/scripting_ug.ditamap

The script does a deep search through submaps and through direct cross-references to files that aren't explicitly included in the map.


Hi Radu,

I completely agree with what you said. Once books reach a certain complexity, authoring and maintenance become more like software development. This is especially true when profiling conditions, content reuse, indirection, and other software-like features are used. We use Git with cascaded release branches, in which work automatically forward-propagates through the branches via merges, just like software.

I think you are on the right track of thinking about how to provide building blocks of functionality, along with ways to tie them together.

Maybe file lists can be one such building block. It would be nice to copy the list of files from one operation (a "Find", or the modified/staged file list in the Git plugin, or the results in the "DITA References" view), then somehow select all those files in the Project view, then run an operation on them (a refactoring operation, maybe another Find, etc.). This would be like manual piping between actions. I'm just thinking out loud...

[jmorales]

Thanks, crispitude, for your idea. Regarding the perl script, it sounds quite useful. I don't have access to a Linux environment, but I might be able to run it on Windows using Strawberry Perl. I have just asked my managers for permission to use Strawberry Perl but it might take a few days to get a reply.

Radu, Thank you also for your interest in our use cases, and for keeping them in mind as you develop future enhancements for Oxygen!