Share via

Introducing a new document model design code named "Hana"

  • Article

With Sandcastle June CTP we are releasing a new documentation design code named “Hana”. We expect the release to be available on June 18, 2007. This presentation layer will be released as a part of Sandcastle and will not be used for Orcas documentation shipping in MSDN anytime soon as we have to make changes to the online infrastructure. We will continue to use VS 2005 presentation for our Orcas release with additional design improvements. I will blog about this soon.

This new documentation presentation layer targets developer audience who need to find information quickly and easily in our documentation that grows significantly with every Visual Studio/.NET Framework release. As new .NET Framework features are released, we must update the documentation design to accommodate the associated new concepts. As a result, we need improvements to the way that we navigate, filter, and display the documentation. These new features allow developers to locate, filter, and sort information in ways that are necessary to perform their job. When this new documentation presentation layer is implemented, user must be able to take advantage of the following features:

  • Persistent language filter to let a user choose a preferred default programming language that automatically shows the associated syntax blocks, code examples, and language keywords that are associated with that language
  • Filter at the member level based on a type’s supported frameworks
  • Filter at the member level based on a type’s supported framework versions
  • Filter at the member level based on a type’s supported platforms
  • Filter on member types
  • Filter on member types’ accessibility modifiers
  • Restrict the documentation disk footprint
  • See more information in less screen space
  • non-English users to easily compare English with non-English documentation pages
  • Syntax Blocks will occupy less space on the screen

Improved filtering to accommodate new technology concepts

New technologies such as Extension Methods and XAML introduce entirely new categories of members and syntax blocks that the filtering mechanism must accommodate. No one view meets all user needs, thus we allow users to manipulate the view to create the display that meets their requirements. For example, a user wants to show only the XAML syntax blocks when they view class pages.

Multiple dimenstions of information

As the number of frameworks increase, we must display multiple dimensions of information, such as the matrix of various framework versions, platforms, types, and members. This requires a sophisticated filter that accommodates all the dimensions, yet does not overwhelm the user with choices. For example, a user wants to only show types that are supported on the Compact Framework.

Filtering Persistence

When a user sets a particular filter, since there are multiple levels of filtering possible, they should not have to reset the filter every time they navigate to a new page. Therefore, the filters must be persistent, meaning that the filter maintains the user’s choices as they navigate the documentation. Specific filters such as member filters do not persist to support searching members using Ctrl-F.

The programming language filter is focused on a user’s role, meaning whether the user is a C# programmer, or a VB programmer. Therefore, filter persistence applies only to the programming language filter. Other filters, such as member accessibility and the type filter on namespace pages should reset to the “All Types” view as a user navigates across the pages. These do not map to a user’s role specifically and instead relate to a sub-category of information they are looking for within their role.

Screen real estate and vertical scrolling

Even at high resolutions, screen real estate is limited given the growing amount of information we must present in the documentation. Previously we introduced collapsible section headers, which allowed a user to hide a section of content that they were not interested in, which reduced the overall vertical topic length and thus reduced the need to scroll. However, as the content grows over time and we add to the number of headers, most reference topics no longer fit on one page. Reducing the amount of time users spend scrolling and making best use of the available screen real estate is very important. For users that spend a lot of time in the documentation, saving a few seconds adds up over time and allows them to be more productive overall. Additionally, comparing elements on a page is easier when there is less scrolling involved.

Users have provided consistent feedback saying that users in non-English locales like to compare localized content with the English version. Currently, switching between versions of topics is extremely difficult and requires a user to maintain a mapping of English URLs to localized URLs. Users need quick and reliable access to multiple language versions of a given documentation page. This is a feature for online side of MSDN and will not impact Sandcastle users.

Page Count

Applying a new presentation layer allows the opportunity to reduce the number of pages of documentation that a user must navigate. For example, when a class overview page also contains the member list (not separate pages), this reduces the amount of TOC navigation needed.

Documentation Disk Footprint

Sharing reference pages across multiple frameworks and versions allows a smaller documentation disk footprint. 

I will blog more details with screen shots soon..

 

Anand..

Comments

  • Anonymous
    June 17, 2007
    Hi Anand, You mention language filtering on code examples.  When using the <code> tag there is no way to specify a language (e.g. C#).  How do you create code examples which will work with language filtering? Kind regards, Jakob.

  • Anonymous
    June 18, 2007
    Bil Simser on An attempt at working with eScrum. Martin Hinshelwood on TFS Event Handler: Prototype Released....

  • Anonymous
    June 18, 2007
    I am excited to announce the availability of June 2007 CTP version for Sandcastle. The latest version

  • Anonymous
    June 18, 2007
    A new version of the Microsoft tools for generating documentation using .Net Assemblies and code is now

  • Anonymous
    June 20, 2007
    We released June CTP version of Sandcastle earlier this week and got some great feedback (and bugs) from

  • Anonymous
    June 21, 2007
    曾经在园子里面看到过有兄弟介绍SandCastle，在VS2005下用来生成文档的，而且是微软官方出品，最近被QA追的比较紧，一直在追文档，于是想到了SandCastle，最近它发布了新的版本，六月CTP版本，决定下载来研究研究，生成一下文档。

  • Anonymous
    June 21, 2007
    曾经在园子里面看到过有兄弟介绍SandCastle，在VS2005下用来生成文档的，而且是微软官方出品，最近被QA追的比较紧，一直在追文档，于是想到了SandCastle，最近它发布了新的版本，六月CTP版本

  • Anonymous
    June 22, 2007
    Microsoft has released another community technology preview of Sandcastle, a tool for creating documentation

  • Anonymous
    August 13, 2007
    More public DocSites online...