As you know, the index (for example, the Index tab in the HTML Help (.CHM file), and in DocCommentXchange) provides a list of topics that are contextually-related to a term you specify when looking for a topic in the documentation.

We are investigating the value and use of the index in our documentation, and are interested in your experience. These questions are open to SQL Anywhere customers and consultants, as well as to SAP internal staff such as support staff and engineers; essentially, any consumer of SQL Anywhere documentation is invited to respond.

  1. Do you use the index provided in the SQL Anywhere documentation to find topics?
  2. If so, how frequently? (Index, what's that? Rarely? Frequently? Exclusively?)
  3. If the index were to go away, how would this impact your documentation experience?
  4. How would you order the three main methods of finding topics, and quantify your use of each: Table of contents (Contents tab) Index (Index tab) String searching (Search tab)

Thanks very much for responding, and for all the valuable ways you contribute improvements to the SQL Anywhere documentation.

~ The SQL Anywhere documentation team

asked 15 Oct '13, 15:39

Laura%20Nevin's gravatar image

Laura Nevin
1.1k2713
accept rate: 66%

edited 15 Oct '13, 17:02

Volker%20Barth's gravatar image

Volker Barth
29.9k294446654


12next »

It is challenging to get a sense as to preference from the responses thus far..

Kidding :)

Seriously, thank you for your responses. The SQL Anywhere docteam also uses the index extensively to do our work, especially for finding the more obscure related topics (as you also do, it seems). Please know that currently there is no plan to remove the index. However, there are always investigations at a more global level in our company (as well as across the writing industry) to ensure that we are maintaining valuable features in our information products. Determining the value of indexes being one of those investigations recently, we decided to engage SQL Anywhere forum users for feedback. Your answers help clarify for us, so thanks again.

Additional responses are welcome, even if they overlap with, or are completely contrary to, what has been posted.

permanent link

answered 18 Oct '13, 14:15

Laura%20Nevin's gravatar image

Laura Nevin
1.1k2713
accept rate: 66%

I almost exclusively (i.e. est. 99.9%) use the index to find information in the documentation. My typical session is (a) go to http://dcx.sybase.com, (b) click on the version of documentation that I want to use (typically always the latest version), (c) click on the index tab, and (d) start typing the word or topic that I want to find until I see the item that I am looking for in the list.

If the index fails to find the information that I want (est. less than 0.1%) then I will use the search tab... but I do this so rarely.

I never use the table of contents. Anytime I have tried to use the TOC - once every year or so - I have given up. Perhaps if I used the TOC more often (and was successful) I would better understand how the TOC is structured and be more efficient at using it? But since the index almost always gives me what I want within a few seconds I have no desire to use the TOC. If the docs did not have a TOC I would most likely not even notice! ;-)

Soooo, as you might guess, I would be very disappointed if the docs did not contain an index. My vote: put the effort into maintaining and improving the index and throw away the TOC (and hence have more time to improve the index! :-)

permanent link

answered 15 Oct '13, 16:08

Mark%20Culp's gravatar image

Mark Culp
22.7k9129266
accept rate: 40%

2

... and included in "improve the index" is maintaining and improving the "related topics" that appear at the bottom of each page.

(15 Oct '13, 16:11) Mark Culp
1

Interesting: I'm quite familiar with parts of the TOC since I have read (old) doc versions somewhat page by page. I do not do this anymore (and the current docs would be too "thick" for that approach, I guess) but sometimes I'm happy to re-read some chapters. Therefore I would surely miss the TOC, too... IMHO, TOC, index, and the links on the pages themselves help to organize all the information really well.

(For all technical information I tend to use regularly, the SA one is truly the best - and possibly the only appropriate one. There is so much noise in so many other help systems.)

(15 Oct '13, 17:00) Volker Barth

Everything that Mark said in his answer applies to me as well. I use the index almost every time I use DCX.

(15 Oct '13, 18:58) Graeme Perrow

I do use the index regularly, and I would surely miss it. - When searching for information, I generally use the index way more often than the TOC - and I use the Search only rarely - usually only for topics not found in the index (particularly for error codes and messages).

Confine this current question on SQL standards and SA 16: I was able to answer that immediately with help of the documentation's index:) (And therefore I should give the according rep points to your team:) And the index often invites to look up related information, a good thing on its own.

permanent link

answered 15 Oct '13, 15:50

Volker%20Barth's gravatar image

Volker Barth
29.9k294446654
accept rate: 32%

edited 15 Oct '13, 15:53

I use both the full text search and the index, but I have to second Mikel, that the results of the full text search are often to overwhelming to be of help. So yes, I would miss the index too. For me the TOC could be removed ;-)

It is laborious to create all this documentation, but be assured you have users who read it.

permanent link

answered 16 Oct '13, 02:26

Martin's gravatar image

Martin
8.6k115149237
accept rate: 14%

As a software developer and user of DCX, the Index tab is my primary search mechanism. It delivers search results that are more focused than any other search technique (even Google).

permanent link

answered 16 Oct '13, 08:58

JBSchueler's gravatar image

JBSchueler
2.0k2836
accept rate: 16%

edited 16 Oct '13, 12:09

CREATE TABLE

  Index: 18 results (with "syntax" being highlighted)
  Search: 1027 results
  Which would you prefer?

(16 Oct '13, 09:04) JBSchueler

My answers:

  1. The index is the primary way I use the doc
  2. I use it almost exclusively
  3. I would visit the doc team and strongly complain if you were serious about removing the index
  4. I use the index maybe 95% of the time, table of contents maybe 4% of the time and search maybe 1% of the time.
permanent link

answered 16 Oct '13, 10:44

Ian%20McHardy's gravatar image

Ian McHardy
2.7k23047
accept rate: 38%

Comment Text Removed

I use the documentation index, almost exclusively, when researching a new topic or diagnosing an issue. For general keywords, the index is much more valuable then the full text search. Consider the query 'UPDATE statement': the index provides valuable links such as the behavior changes between versions and quick, easy access to the syntax pages. On the other hand, the full text search results are much less organized for keywords like this.

Another example would be diagnosing a issue with database mirroring. An index query for 'Mirroring' presents you with quick links to the tutorial and pages like 'recovering from primary server failure'. These would be much more time consuming to find in the TOC (especially for issues that could be considered to be in more then one category). Often the index itself solves issues! After entering in a general keyword, a page is brought to your attention about a caveat that you had previously not thought of.

If the index were to go away, it would greatly reduce the value of the documentation to me.

The index would be my first 'go-to' method of finding information. I normally fall back to the TOC if I need to learn more about the high-level function of a feature, and fall back to the search if I have a specific error message.

Thanks for all the hard work maintaining and updating this valuable resource!

permanent link

answered 15 Oct '13, 16:29

Mikel%20Rychliski's gravatar image

Mikel Rychliski
2.1k1641
accept rate: 30%

Index primarily, Search a distant second, Google third, Contents rarely, Favorites never ever not even once.

Most common usage...

  • Index to find the main "syntax" entry for a statement, something that Search is useless for.
  • Search to see the "Location" column, especially when looking for references in "Changes and Upgrading" topics.
  • Search to see words highlighted in topic text on the right side, especially useful in large catch-all topics that talk about a myriad of sub-topics (SELECT, FROM, etc).
  • Search for items that don't have topics of their own; e.g., error codes, command line codes (-x etcetera).
  • Contents, usually after finding a topic via Index or Search, to see the "context" of the topic, and what other topics are nearby. This can be useful when looking for a higher-level topic to use in the answer to a question ("This and other topics are discussed in xxx.")

Suggestions:

  • Bold text for main subtopics in Index; e.g., "syntax" topics for SQL statements and commands, which are often buried down in a long-and-varying-length-for-different-topics list of subtopics.
  • Dump the popup box when clicking on a main topic, and just go the main subtopic; e.g., when I click on "SELECT statement" I don't want to see an endless popup list of random topics, I WANT TO GO TO THE STEENKING SELECT TOPIC... to channel Highlander, "There can be only one." :)
  • Tighten up the Index list. For example, "SELECT statement" is arguably the most important topic of all, certainly the most important "SELECT" topic, yet it appears as the ninth main topic that starts with the word "SELECT". The first "SELECT" topic is the pathetically unpopular "converting T-SQL". I suggest you get a pair of pliers and a blowtorch and go to work on the Index list... redesign it for human consumption.
  • More jump-down link lists in long topics. Scrolling ... down ... page ... after ... page ... to ... find ... the ... discussion ... of ... the ... 47th ... keyword ... in ... the ... statement ... syntax ... gets ... tiring.
  • Make inside-topic links work from outside DCX... this would allow direct links from outside articles to sections way ... down ... inside ... long ... topics, something which doesn't work now (even if DCX itself has a link to an internal sub-section, it only works from inside DCX).
  • Make Search accessible via direct links from outside DCX; i.e., an URL that specifies the DCX site, the Help document inside DCX, and the Search keywords. This would eliminate most Google searches of the DCX domain.
  • Dump Favorites, unless a fan pipes up :)
permanent link

answered 16 Oct '13, 08:25

Breck%20Carter's gravatar image

Breck Carter
27.3k424585836
accept rate: 21%

1

Great suggestions - and I surely second the suggestion that the main DML/DDL statements should be easier reachable in the index. Like Breck, I usually want to see the syntax page - and it's nice that DCX at least already does highlicht that subtopic.

(16 Oct '13, 09:51) Volker Barth

Dump Favorites

Gosh, I have never ever realised that tab in the HTML help until now - should I say I don't need it as it is empty? :)

(16 Oct '13, 09:54) Volker Barth
1

Dump the popup box when clicking on a main topic, and just go the main subtopic;

Absolutely

(17 Oct '13, 06:56) Justin Willey

Index is my first attempt to find anything whether using the local CHM or online documentation.

If the index went away, it would take me a lot more time to find what I want searching through all the hits in the search page, and would therefore be in a worse mood while working with the product. Search terms tend to be overloaded and the index helps me to narrow the context because you've done a fairly good job with it so far.

In order of use: Index tab, Search tab, Contents tab (with the exception of when I refer to it so often I know exactly where it is in the table of contents.

permanent link

answered 16 Oct '13, 16:48

Ron%20Emmert's gravatar image

Ron Emmert
33651118
accept rate: 12%

edited 16 Oct '13, 16:55

Like the others, I depend mostly on the index, using the TOC only when it's for reading about a specific theme, e.g. HA. I would miss the index sorely, if it wasn't there, and would be tempted to post a question before trying to browse the docs.

Please keep on the good work. Kudos to the doc team!

permanent link

answered 16 Oct '13, 03:22

Reimer%20Pods's gravatar image

Reimer Pods
4.2k334481
accept rate: 12%

Your answer
toggle preview

Follow this question

By Email:

Once you sign in you will be able to subscribe for any updates here

By RSS:

Answers

Answers and Comments

Markdown Basics

  • *italic* or _italic_
  • **bold** or __bold__
  • link:[text](http://url.com/ "title")
  • image?![alt text](/path/img.jpg "title")
  • numbered list: 1. Foo 2. Bar
  • to add a line break simply add two spaces to where you would like the new line to be.
  • basic HTML tags are also supported

Question tags:

×408
×196
×137
×79
×15

question asked: 15 Oct '13, 15:39

question was seen: 2,142 times

last updated: 18 Oct '13, 14:15