REQUEST FOR COMMENTS: Removing type links from the Syntax section

Coordinator
Dec 16, 2012 at 2:19 AM

For Help Viewer 2.0, it has come to light that links to types in the Syntax section that use the ID style (i.e. links within the Help Viewer collection such as those to types within the documented assembly) no longer work because it doesn't bother updating their ms-xhelp URL if the link is within a pre element or at least one in that section.  This affects all presentation styles.  Work item: http://shfb.codeplex.com/workitem/33563

It can probably be fixed with another JavaScript hack like the one for getting the URL for background images from the Favorites icon URL in branding.js for the VS2010 style.

Another alternative is to update the syntax components so that they no longer render links for types at all in the Syntax section.

I'm leaning towards just removing the links in the Syntax section for the following reason:  Links to the types are currently rendered for parameters in the Parameters section.  A link for the return value type is not rendered yet but that can be added easily enough.  Those links effectively negate the need to have them in the Syntax section as well since the types would be accessible via links elsewhere on the page.  This appears to be the direction taken on MSDN now and it does make sense and gets rid of duplicate links.

So, the question is this:  If they were removed from the Syntax section would anyone really miss them considering the type information links would be available elsewhere on the page?

Unless there are compelling arguments for keeping them, I'll look at removing them at some point in the future from the syntax generation components and adding a type link for the return value in all presentation styles.  Reply here with any relevant thoughts.  Thanks.

Eric

 

Dec 16, 2012 at 3:24 AM

I don't see any problem with doing that. I find it annoying that on some websites a single paragraph has 5+ links to the same page, all links using the same phrase.

The worst I have seen is over 30 links to the same page in one paragraph. I lost count then. The entire paragraph was links.

Dec 17, 2012 at 8:22 AM

Adding the return type to the "returns" section seems to be a good idea anyway (if only for symmetry reasons). Removing them from the syntax section would be ok, I guess, however I'm not sure if these are the only occurrences of links in a "pre" context.

Dec 17, 2012 at 4:38 PM

Following the lead of the MSDN documentation is probably a good idea. It would be nice if someday it stopped changing so much. I do believe the current MSDN style is better than the older ones.

Dec 18, 2012 at 4:21 PM

I could go either way on this, but I'd tend to go with what MSDN does.  One thing that I don't think has been addressed: is there a convenient way to get at the interface types that are specified in the syntax section of classes?  As far as I know, that's the only place they are listed and also linked.

Dec 19, 2012 at 2:24 PM
jaquadro wrote:

I could go either way on this, but I'd tend to go with what MSDN does.  One thing that I don't think has been addressed: is there a convenient way to get at the interface types that are specified in the syntax section of classes?  As far as I know, that's the only place they are listed and also linked.

I was concerned about this as well. There is no link to the interface types. The only way to get to them is to use the index. This is a limitation of Help Viewer 2.0. If it is good enough for Microsoft documentation, it is good enough for us, for now. Perhaps they will make an official fix, but I don't see anyone complaining.

Dec 19, 2012 at 2:42 PM
jaquadro wrote:

I could go either way on this, but I'd tend to go with what MSDN does.  One thing that I don't think has been addressed: is there a convenient way to get at the interface types that are specified in the syntax section of classes?  As far as I know, that's the only place they are listed and also linked.

You are right! If we are going to change the style anyway, it would be nice to have a section "implemented interfaces" or whatever, in parallel to the Inheritance Hierarchy. It's not that important since we usually mention the interfaces in the summary, though. That said, I guess creating a separate section ourselves probably won't be too difficult.

Coordinator
Dec 19, 2012 at 3:23 PM

I noticed that the members do indicate which interface members they implement but the class itself does not.  I agree that it should so that's a change worth making.  When I went to see what the current MSDN does, I see today that the MSDN format has changed yet again and they've done away with the separate Members page.  The class members now appear on the class page itself.  Maybe they'll find a format they like and stick with it for a while one of these days.  Trying to keep up with the everchanging format seems like a losing battle.

Eric

 

Coordinator
Feb 22, 2013 at 7:35 PM
Since nobody seems to care if the links stay, I'll see about removing them in a future release and implementing the other changes mentioned such as adding a link to the return value type.

Eric