bzr-windows team mailing list archive

["Dave Murray" <irongut@xxxxxxxxxxxxxxxxxxxx>]

Forgot to hit reply all on this earlier... (I hate Outlook)

-----Original Message-----
From: Ian Clatworthy
Sent: 03 September 2009 07:44

> 1. Ease of navigation

The index is empty and needs to be filled. It's the usual method of
searching and more important than the search tab. It's been a while
since I wrote a help file but from memory the index is built of keywords
that you specify in each topic. I'd expect Sphinx to build the list for
you or at least have some way of letting you add them to a topic.

> 2. Scope and impact on searching

The free text search works well except it is giving me results in
Russian as well as English. I don't think I've ever seen a help file do
that before, the usual practice is to include separate help files for
different languages. The installer should have an option for each
available language and only install those selected. I'd put the
developer docs in a separate file as well but they would also work as a
separate book / top level chapter in the main file.

I did spot a minor bug in the text search, the topic 'Bazaar Performance
Roadmap' showed up for a search I did and in the list box it's title was
prefixed by several garbage / unprintable characters. They don't appear
in the topic itself. I can provide a screenshot if needed.

> 3. Granularity and impact on printing.

I don't think printing needs to be a consideration but topics shouldn't
be so long that they put you off reading them or too short requiring
multiple topics to find the information you are looking for. I've not
had a lot of time but from what I've read so far the topic sizes look
good.

One thing I don't like is that there are too many chapters, everything
seems to be a chapter and there are very few topics. Take the release
notes for 1.18 as an example... Atm the release notes show as a chapter
in the contents list and items like New Features and Bug Fixes are
topics. But, when you read the release notes it is all one page. So the
release notes should be the topic and the Bug fixes, etc should just be
headings within that topic and not appear in the contents list.

On an aesthetic level I think the default font size is too large. It is
a lot larger than other help files I use regularly. But, it can be
adjusted by the user and looks fine once I knock it down a few steps.

Thanks,
Dave.

Dave Murray
Glasgow, Scotland
irongut@xxxxxxxxxxxxxxxxxxxx