1

Documentation without the use of webframe.html?

Michael Mortensen

25 January 2013 00:37

None

Follow

I like the new 2012 template style documentation for websites a lot.

However it is still in a frame version .. will there be a version without the webframe.html solution?
I am thinking an examples like the MSDN website: http://msdn.microsoft.com/en-us/library/system.net.asp, which have several advantages when talking SEO and navigation in general. Just try to go one down, http://msdn.microsoft.com/en-us/library/system.net.authenticationmanager.aspx

Well .. keep up the good work - I hope to see a template without the usage of frames .. similar to the Microsoft solution linked above, but with the nice touch of Document! X styling :-)

• Facebook
• Twitter
• LinkedIn

2 comments

• 0
  
  Richard Sloggett 25 January 2013 09:08

  We don't have any plans for removing frames at present. Although frames have in the past got a bad rep for misuse, iframes (which is what we are using the 2012 template rather than a frameset) are a permanent part of the HTML5 spec and (in our view) are ideally suited for online help scenario.

  An IFrames based output has a couple of really important advantages: Firstly, the peripheral content does not need to be reloaded as you rmove between content pages - so you can have a Table of Contents / Index with persistent selection. Look at MSDN as an example of the limitations of an in-page ToC - it is difficult to 'explore' the class hierarchy - as you scroll the Table of Contents, the page scrolls with it and each time you move a level the page refreshes, the Table of Contents changes and you lose your context. In terms of a frameless implementation, MSDN does have an important advantage in that the Table of Contents is served as Ajax from a web server as you drill down - because the content that Document! X generates has to be able to run without server side processing the whole Toc must be loaded, which is not something we want to be doing on a page refresh, which would be necessary in a frameless implementation.

  The second really important advantage of an IFrame implementation is sandboxing - the javascript, page state, styles in each IFrame are sandboxed from each other - if you have a frameless implementation you need to be absolutely sure that all the script files in all the different areas (including the main content area) work without conflict. That is a significant constraint for a general purpose authoring tool and means that users would need to thoroughly test all their generated output in the web output as well as whilst they are authoring.

  In terms of disadvantages - the 2012 template updates the url to reflects the current content page, so in practical terms the implementation is very similar to a frameless one. Search Engines will happily index content, even in the older Frameset implementation - just do a google search for "realworld site:innovasys.com" - we haven't done anything specific to have google index that content.

  We did look carefully at the web output implementation when designing the new 2012 web output template and came to the conclusion that the significant advantages of an IFrame based output, along with the fact that IFrames are a part of the HTML5 spec, outweighed any perceived disadvantages compared to a frameless output.

  We would love to hear your views on this, particularly if you can see any disadvantages to an IFrame implementation that we might not be aware of.

• 1
  
  Michael Mortensen 25 January 2013 15:47

  Hi Richard,

  Thank you for the very thorough assessment of why you have chosen iframe over div elements.

  You make some very good points but in regards to SEO it would be better with the full TOC together with your content.

  One of the reasons for this is, that search engines will associate the words in the TOC with the content and hence increase the change for other fellows code-geeks to get what they want. 
  Another very valid reason IMO is the direct link; a search engine may link directly to the content leaving the user without a TOC why - if you choose to continue with the frame/iframe strategy - you could maybe include something like my quick-n-dirty implementation:

  <script type="text/javascript">
  	if (top.location.href == self.location.href)
  	top.location.href = '/webframe.html?' + top.location.pathname;
  	</script>

  This assures that the visitor will get the TOC, but not nicely expanded and syncronized to the right location.
  Also, some search engines are not happy with these "workarounds", why they might mistakenly  associate your website with suspicious activity.

  As always, I am very pleased with your product; I just think some of the points highlighted here can do a lot to the end user experience.

  Let me know if I need to elaborate further.