The index in the SQL Anywhere documentation – useful to you?

[Former Member]

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

[Former Member · Accepted solution]

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.

[MarkCulp]

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! 🙂

[MarkCulp]

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

[VolkerBarth]

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.)

[graeme_perrow]

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

[ian_mchardy]

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.

[jack_schueler]

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).

[jack_schueler]

CREATE TABLE

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

[MCMartin]

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.

[VolkerBarth]

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.

[Former Member]

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.

[Breck_Carter]

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 🙂

[VolkerBarth]

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.

[VolkerBarth]

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? 🙂

[justin_willey]

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

Absolutely

[former_SQLA_member1694878]

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!

[former_SQLA_member1694870]

I also always use the index as my first (and almost the only) attempt to find answers from DCX.

[Former Member]

Do you use the index provided in the SQL Anywhere documentation to find topics?

Yes, many times a day, every day. Its advantage is that I can be assured that an index entry points at some significant reference to some feature, rather than an irrelevant passing reference.

The main thing I look up is SQL statement syntax.

If the index were to go away, how would this impact your documentation experience?

I would be one sad puppy. Look at those eyes! How could you take the index away from him?

How would you order the three main methods of finding topics...

1. Index - used all the time
2. Searching - used one a week
3. Table of contents - used once a week, maybe

[justin_willey]

Like everyone else (so far), the Index is my overwhelming most frequent starting point. Contents for a few specific topics, Search almost only for error messages (and occasionally, when I haven't found what I'm looking for and not sure what the right terminology is).

I appreciate that keeping a good index maintained is a distinctly non-trivial task; but I would argue that it is almost the most important part of creating useful documentation for a complex product. Please don't be tempted down a purely automated direction - it will just end up like the search. It's not the search functionality's fault that it is of limited use - it is the nature of the material that it is dealing with - it's hard to discuss almost any topic about an RDMS without mentioning "table" - so naturally searching for "table" isn't going to help much!

I would strongly support the suggestions to do with prioritising certain key articles within index topics.

[former_SQLA_member1694900]

Please do not throw away the index!

[reimer_pods]

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!