Maintaining conceptual content links

Topics: User Forum
Nov 21, 2014 at 2:36 PM
Most of the content in our help files is manually authored conceptual content files. When we include links in certain contexts (such as within <relatedTopics>), I tend to prefer to not put any inner text in the <link> element so that the title stays in sync with the topic title. But, this, of course, makes it difficult to see what I'm linking to when editing the source. I've tried putting manual comments next to the link, but these, of course, don't stay in sync as the title changes (and, annoyingly, they get repositioned below the <link> element when I format the document via CTRL-K, CTRL-D (as I habitually do). Any advice on managing this? I've included a sample of what I currently do below.
    <relatedTopics>
        <link xlink:href="5c85f23b-1c7d-4779-9cd1-1258a0b8e0c0" /> 
        <link xlink:href="acc61cb7-9147-4243-82c0-23b443170f64" /> 
        <link xlink:href="272e65e6-eb45-4dfd-a2a5-4d2e36e2c1be" />
        <link xlink:href="40438dda-c881-4bd1-ae18-4359016805c8" />
        <link xlink:href="5a3190c9-2455-4fae-8ea7-411c4ce690f3" /> 
    </relatedTopics>
Coordinator
Nov 21, 2014 at 3:13 PM
Edited Nov 21, 2014 at 3:13 PM
There isn't a way to know what the link refers to short of looking it up using the Find option in the content layout editor. A workaround would be to preview the topic since they you can see what it's linking to. It's not an option I use but a while ago someone asked me to remove the requirement that topic IDs be GUIDs. They can be any text string you like now. Of course, the down side is that if you change the ID text to something else to make it more relevant if the topic changes you lose the connection between the topic and the content layout file and any links that refer to it and have to keep them in synch again manually. GUIDs aren't perfect but they do remove the need to keep the IDs in sync all over the place.

Eric
Nov 21, 2014 at 3:19 PM
Yep, yep. Thanks Eric. I prefer GUIDs (but, I'm an old grizzled COM guy, so....). And, the Find option is reasonable -- would be really bad without that. Do you then do the same as me in terms of leaving <link> elements free of inner text?

Would be cool to have somebody write a VS editor extension that added a topic title adornment for <link>'s.
Coordinator
Nov 21, 2014 at 7:34 PM
Yes, I typically leave them as self-closing elements unless the topic title doesn't fit well with the flow of the particular sentence. I forgot about the Entity References window too. It has a lookup option as well which saves having to open the content layout file for the project. It refreshes its content based on the selected project which is useful if you have multiple help projects in one solution.

The editor extension is a good idea. I'll be publishing a new release this weekend so it'll have to wait for a future release.

Eric
Coordinator
Dec 8, 2014 at 4:28 AM
Just a quick update. I was able to implement info tool tips and "go to definition/file" for image, token, codeReference, codeEntityReference, and link elements. The tool tip for image and link elements shows the alternate text/title and the filename. Ctrl+clicking on them goes to the containing file. For code entity references, it only works for C# projects within the current solution (couldn't find a way to navigate to definitions outside of them) but that is more likely than not the content you are most interested in. It also shows the info tool tip for the topic element in MAML files so that you can see the title for the current topic. As a bonus, it also works the same way in C# XML comments for any element with a cref attribute (again C# projects local to the solution), conceptualLink elements, and token elements.

Now that I've been using it, it's a feature I can't live without. I'm very pleased with how it turned out. I've got some more testing to do and then I'll probably publish another update within a couple of weeks since I've got a couple of other fixes I'd like to publish too. It'll be in that release.

Eric
Marked as answer by EWoodruff on 12/7/2014 at 9:29 PM
Dec 8, 2014 at 6:10 PM
Sounds great. Will look forward to seeing that.