[platform-help-dev] Help navigation scalability

["Konrad Kolosowski" <konradk@xxxxxxxxxx>]

Help faces scalability issue with navigation consisting of large books
(over 2000 nodes), which needs to be solved (javadoc for a small product
can easily exceed that if all the topics are included in the navigation).
Below is a discussion of some of the considered solution to the problem,
and the one that may be most appropriate.  Anybody having interest in
topics navigation presentation, look or feel please scan through the note
and comment, whether it is any details or you would rather see a different
approach.

When navigation contains a large number of topics, the size of HTML that is
generated and displayed in the navigation frame of a browser is large.  In
2.1 help implementation, Contents view displays either a list of books or
list of books with one complete book.  The loaded and displayed books is
not fully expanded, and not every topic is immediately visible to the user,
but the book is completely loaded in the browser.  This solution works well
when large documentation set is spread among many smaller books, and none
of the books consists of more than couple of thousand topics.
Eclipse's documentation meets the constrains of limited size books, but
there exists other products whose documentation is large and cannot
naturally be split into small books.  Additionally, by linking smaller
books, it is always possible to create a large one that aggregates several
smaller ones.

The problems that arise when book exceed few thousand of topics are:
P1.  Slow loading of navigation.  The size of the generated HTML for a
book, dictates the delay that the user is going to experience when the book
is loaded in the browser through the network.
P2.  Incomplete loading of navigation in the browser.  There were cases
reported where on some machines the navigation book of over 10000 topics
was consistently not completely loaded.  Receiving of the stream was being
terminated after receiving most of the HTML.  This issue does not identify
a total size of a book or size of documents loaded in all help frames as a
limiting factor, but rather a large number of bytes loaded from a server in
a single connection.
P3.  Expanding or collapsing branches, results in browser performing long
operations in the background and being unresponsive for a number of
seconds.  Every topic in the navigation corresponds to several HTML
elements, and corresponing objects created in the browser DOM, including
images and link to a topic.  It seems that browsers cannot handle such a
large number of elements in an efficient manner, even if most of the
element are invisible (collapsed branches have hidden style).
P4.  Opening a different book when a large one is being displayed, results
in an additional delay - unloading of a book is not instantaneous.  A total
number of HTML elements loaded in a frame, and are accounted for by the
browser seem to be the cause.
P5.  Opening help to a specific topic, or opening a search result from a
search performed in a workbench or synchronize action performed by a user
takes long.  Locating a topic in loaded book, expanding tree branches and
selecting topic is implemented using JavaScript.  To locate a topic in a
tree a linear search is performed.

Loading of whole book from a server that keeps a complete model to a
browser as is done in Eclipse 2.1 help greatly improves user experience
when browsing small/medium size books.  After opening a book in the
navigation, user operation on the tree in help UI have unnoticeable
response time.  Communication with a server is not necessary for every
click, as large chunk of a model (a book) is loaded in a browser, and
revealing more topics is performed using JavaScript.  However, advantages
of loading a model diminish as model get large, and the discussed issues
become dominant.

There several solutions can be considered to the problem, some of the
interesting ones:
1.  Eliminate network delay between the browser and the server that holds a
model, and access model through API upon user action.
This solution is not feasible in the infocenter scenario, where user is
browsing help on a different physical machine than one the server is
running on.
2.  Replicate a model on a user machine, outside of a This browser can then
access local model.  This solution alone will not solve P1 as the model
still needs to be transferred through the network to the client machine.
3.   tree can be shown in a browser with all the branches collapsed, with
the exception of the branch leading to a selected topic.  This limits
visibility to the topic, its ancestors, as well as topic's and ancestor's
siblings.  This idea was implemented on the first level of the tree in 2.1
help.  It is only possible for a user to see one book expanded, while all
other are always shown collapsed.  The disadvantage is that expanding any
sibling topic changes visibility and requires reloading of the tree from
the server to reflect the new hierarchy.  It also prevents users from
looking at two expanded branches at the same time.
4.  Select a different UI paradigm that will limit a visibility of a model
to a part make sense in a context of currently selected topic.  An example
is a navigation UI showing ancestor's hierarchy in the form of bread crumb,
and showing all children topics as a list.  This presentation reveals even
smaller part of the navigation to the user.  Its advantage is that there is
no tree, that is expected to react instantly to user actions.  Every click
in this example would result in a different bread-crumb and different
links.  The experience would mimic browsing internet, where every click
that changes the context results in reloading of a frame.  The delay due to
reloading of navigation is expected, and natural.
5.  Continue to use a tree for presentation of topic navigation, but lazily
load parts of the model from the server.  This would mean that small HTML
file is downloaded from the server into a browser to show expanded nodes in
a tree.  User action to expand another branch not viewed yet in a current
session, results in downloading a new part of the model, and merging with
model that is already in the browser's memory.  Collapsing a branch will
not eliminate this model part from the browser memory.  As a result, a
model kept on the browser, grows slowly to support displayed tree branches,
but never decreases in size within a current browsing session.  If a user
browses large topic tree, especially if the tree is wide, over a time this
solution will run into problems P3-P5, where browser cannot handle the
large model it has.
6.  Create a mechanism for identifying smaller block within a large top
level book.  The block could be considered as smaller books within a larger
book.  The presentation of a large top level book would consist of a tree,
similar to one in 2.1 help, but the node identified as a sub book would not
be expandable.  Selecting such a node would replace a book displayed in the
navigation by the smaller book.  The action would be similar to "go into",
except that it would not be possible to go into any topic, but only into a
node designed by authors to be such.

I propose a solution for Help 2.2 that is a variation of idea 5.  For a
smaller book, the help system can display a whole book.  When a book is
large, a limited number of topics is transferred first and displayed in the
client browser.  Not to introduce the delay for every new topic expansion,
the initial tree model transferred to the client can consist of more than
one level of topics, but ensuring the total number of topics is fraction of
maximum number of topics manageable by the browser.  User can then browser
few top levels without any additional delay, and only upon trying to expand
a topic whose children are not available in the model fragment on the
browser another small chunk of navigation will be transferred and merged
with navigation already existing on the client.  The transferred model can
again consist of several levels (if the tree is not very wide) to minimize
the effect of network delay overhead.  To avoid eventually holding to many
topics in a browser, a solution can be investigated to purge not needed
parts of the topic tree.   To minimize visibility of this operation to the
user a tree can be trimmed down from unexpanded branches, or even least
recently expanded ones, if necessary.

I favor this approach of lazily loading, not the simplest, but preserving
the UI presentation of navigation that was used in Eclipse 2.1.  We
received no feedback that the tree used in 2.1 is too powerful and could be
replaced with more limited one.  There exist requests even more features
request for the navigation tree, like "expand all" action (that clearly
cannot be implemented if scalability is in mind).

Konrad Kolosowski