|
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.
Thanks very much for responding, and for all the valuable ways you contribute improvements to the SQL Anywhere documentation. ~ The SQL Anywhere documentation team |
|
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. |
|
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! :-) 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. |
|
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. |
|
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). CREATE TABLE Index: 18 results (with "syntax" being highlighted) Search: 1027 results Which would you prefer?
(16 Oct '13, 09:04)
JBSchueler
|
|
My answers:
|
|
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! |
|
Index primarily, Search a distant second, Google third, Contents rarely, Favorites never ever not even once. Most common usage...
Suggestions:
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
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
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. |
|
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. |
