Page 1 of 1

Visual structure with links/conrefs of the project

Posted: Mon Mar 21, 2016 12:23 pm
by nanotec
I was asked by a co-worker a view days ago, if there is a graphical view (or kind of a tree view) for a DITA project, that shows all the relations between the files, links, conrefs a.s.o of a ditamap. The "outline" view provides already a lot of information, but not everything we sometimes need.

I did a quick search, but couldn't find a plugin or a build-in function for this, but please let me know if there is already one.

The user story is quite simple: when editing any part, that is pulled to one or more files via conref, it is quite easy to break something logically or make something wired out of it at the destination. In order to avoid that, we're checking all destinations manually by searching the ID at the moment - which is quite time consuming. Moreover, it happens sometimes that I simply forget that (for instance) a table or a concept gets pulled by a conref.

The tree view should include:
  • The files included in the ditamap.
  • The links between the files.
  • Especially conref (pull) destinations.
Is this something, that could be done or implemented?

Regards,
Bernhard

Re: Visual structure with links/conrefs of the project

Posted: Mon Mar 21, 2016 2:57 pm
by Radu
Hi Bernard,

I understand the use case, we did have some future plans to create some kind of hierarchy view of the DITA Project so I will add your vote for it.
This is more of a CMS-related feature (there are commercial CMSs which have such support) because the view needs to have some caching and that caching needs to be updated dynamically when DITA content is modified. As you can modify DITA content also outside of Oxygen by directly editing files using other applications, Oxygen will not know 100% when changes are made to topics but it could provide an F5 Refresh functionality to reload the entire cache which holds a graph representing all relations in the DITA Map.

So the problem using the current "Search References" functionality is that it takes some time to deliver all references to the element, right?
Are you also using conref push functionality in your project?
Also, would you expect this view to update in real time, for example each time new links between different components are added in topics and maps?

If you have a clear idea about how this view would behave, please give us more details about what you expect.

Let's say for example you are editing a DITA topic. The view is opened on the side. The view would probably automatically select in it the file name of the edited topic. Then you expand that file name and you would have two groups, the outgoing links group showing all links from this topic to others (either via @href or @keyref) and incoming link which would show all topics (and maps) which point to it along with information about the elements they point to. Also maybe there would be a "Reuse" group which would also have two sub-groups, one for conrefs to this topic and one for conrefs this topic makes to others.

Regards,
Radu

Re: Visual structure with links/conrefs of the project

Posted: Tue Mar 22, 2016 10:48 am
by nanotec
Hi Radu,
thanks for the quick reply.
So the problem using the current "Search References" functionality is that it takes some time to deliver all references to the element, right?
I have to say that I didn't know about this feature (if you mean the feature described here), I was using an external search tool. My bad, I'll have a deeper look into it.

In my opinion the problem isn't the search itself, but being remembered that content is pulled elsewhere.
Are you also using conref push functionality in your project?
No, not at the moment. I try to keep stuff simple to let as may co-worker participate in our documentation as possible. The support in the editor for pull confrefs via the "Reuse content from a document"-button is extremely good, easy to understand and very simple to use. Therefore pulled conrefs was my first choice. But I'll have a look at pushed conrefs, as well.
Also, would you expect this view to update in real time, for example each time new links between different components are added in topics and maps?
Me in personal: no, I wouldn't. But I do a lot of XML stuff and programming and therefore I know how hard this can get with detecting loops in the tree and all that jazz. I don't have a problem with a button "scan project" that will refresh everything. But I that's only my opinion, maybe other users do want to have this feature.
If you have a clear idea about how this view would behave, please give us more details about what you expect.
Well, I haven rethought this very deeply and I would highly suggest asking more user than just me about a new feature :-) I like the idea of the view listing all "ingoing" and "outgoing" connections. This will help a lot during editing, especially if you can easily follow these links to check the destination files.

I think one thing is worth mentioning: Let's say you man have opened a ditamap and editing a topic. This topic can get pulled by a dita-file, which is not part of the current ditamap.

Thank you very much for all your effort, best regards,
Bernhard

Re: Visual structure with links/conrefs of the project

Posted: Tue Mar 22, 2016 12:33 pm
by Radu
Hi Bernhard,
I have to say that I didn't know about this feature (if you mean the feature described here), I was using an external search tool. My bad, I'll have a deeper look into it.
When you open a DITA topic in the Author visual editing mode you can right click inside it somewhere and choose in the contextual menu Search References. It will search all references to it in the context of the current DITA map opened in the DITA Maps Manager view. This is the action I was referring to.
In my opinion the problem isn't the search itself, but being remembered that content is pulled elsewhere.
Maybe it would be nice that when you place the caret somewhere and we already know via that internal caching that the element is reused from some place else we could show a small widget on the left stripe or in the breadcrumb. This would warn you that the content you are editing is being used or linked to in multiple places. And you could click that widget and it would show all references to the element.

All this aside, as a best practice, you should keep all your reused content in special topics located in special folder. Whenever a writer edits such a topic, they will know that any content there is probably referenced in multiple places.
But there are still problems with linking (when you modify a section you would like to know that it's linked in multiple places) and even with entire topics referenced in multiple places in the DITA Map (because the content of the topic must fit each of those context in the DITA Map). For this latter issue we added in the breadrcumb some information about how many times the current edited topic is referenced in the DITA Map and two buttons to navigate between these topic references in the DITA Map.
I think one thing is worth mentioning: Let's say you man have opened a ditamap and editing a topic. This topic can get pulled by a dita-file, which is not part of the current ditamap.
Indeed, right now we consider as editing context a single DITA Map but some projects have more than one DITA Map. So the editing context should be a pool composed of all these DITA maps.

Regards,
Radu