CIAO documentation features
which are missing or need improvement

9 - technical discussions

12 - ahelp pages usually need more content, such as brief descriptions
     of how the tools work, citations to ApJ (or other) papers on which
     tasks are based, etc.

     Online thread URLs have a nasty habit of changing.  This can get very annoying!

13 - Not easy to find good detailed descriptions of standard products

15 - providing  more examples under the ahelp pages of some of the
     more complex uses of certai commands.

18 - The web pages are too hard to follow -- to many hyperlinks.  A
     simple linear thread would be better.

19 - Further expansion of the threads.  For example, why do all the
     threads use PI bins instead of PHA?

21 - The "bugs" link at the bottom of every ahelp web page should go to
     the bugs list for THAT TOOL, rather than to the list of all tools.

     The cross-referencing between threads is often useful, but is
     sometimes just confusing, particularly when the cross-references send
     you several documents deep. In cases like that, it would be nice if
     the threads could be a bit more self-contained.

22 - Documentation which descibes what the scripts do, and what's
     called by the script would be useful.

23 - Some aspects of the current state of calibration are well-hidden to 
     the user, specifically the areas where calibration is extremely 
     uncertain are not as well-defined as they could be.
  
24 - The threads should offer much more explanation of the choices used.

28 - If I don't use CIAO for a while, I always forget the exact syntax
     for doing certain things (e.g., filtering on a spatial region).  It 
     always takes me a while to find different examples of it again.  It 
     would be helpful to have this information linked within every thread 
     where it's relevant.

32 - The manual/online help could use a little more technical info;
     for instance, exactly how does sherpa go about subtracting the
     background, or simultaneously fitting BG and source; how does it deal
     with pixels on the boundary of a region defined in ds9; etc.

35 - More examples of analysis chains need to be given, particularly for
     grating spectroscopy.

39 - More warning regarding change of CIAO version while using same data

43 - brief usage messages, as common in linux w/ --help

     more top-down "ABC" guides, rather than "bottom-up" add-ons to web
     pages, which tend to fragment reading.

44 - *Printable* ABC Guides desperately needed.  Threads are great once
     you know what you're doing, but a terrible way to learn.  There needs
     to be something that you can print and read on the john.
     There's a certain cavalier attitude on the threads.  All references to
     the 3 ms readout time of CC mode should be expunged.  It's 2.85 ms, and
     thinking "Oh, that's close enough to 3, so let's just put 3 in 90% of
     the threads" really isn't good enough.

47 - The main thing missing in almost all the threads are discussions of the various
     assumptions and limitations that go into the analysis. Perhaps an expert user
     class of documentation needs to be considered. The threads seem to address
     the needs of the novice user fairly well already. Time to move beyond the 
     lowest common denominator service level.

49 - More understandable examples on ahelp pages.

53 - threads! - Would like to know the general principles, and
     flowchart of SDP. Please don't ask me to treat x-ray analysis as a
     black box..

59 - Information on calibration and potential problems with interpretation of the results.

60 - The documentation about script is not provided.

63 - The online ahelp pages take too many clicks to get to, and could
     easily do with more examples.  More examples=better, always!!

64 - Please include more (and more diverse) examples in the ahelp.

69 - It would be nice to have a bit more information on the background
     dataset files in the CALDB. e.g. which datasets can be used with VF
     mode reprocessing on. As far as I can tell there is not much
     documentation on this and some of the header keywords in the files are
     misleading (e.g. header claims VF mode but the necessary columns are
     not there to use with a VF cleaned dataset).

     I also find the helpdesk search interface to be somewhat awkward. I
     find it very slow to use, and I often have to search to lots of
     irrelevant queries before finding anything usefull (which is anoying
     given that each one can take a long time to load).

75 - accuracy of threads (particularly hrc); lack of printable "cookbook" to browse

81 - more examples of correct analysis are needed, mainly as
     threads. Maybe authors of good papers could be invited to write a
     thread, explaining how (and why) they did various procedures in their
     analysis 

82 - Some details of programs are poorly documented or difficult to find.

83 - It is hard to find the older versions of the documents
     e.g. threads for CIAO ver 2.2

84 - exceptions

90 - It is difficult when you have an idea of what you want to do, but don't
     know what task, thread, etc. will do it.  Typing in keywords like "bin"
     doesn't produce output as useful as it could be.

     Even by somewhat familiar person as myself, some of the dictionary 
     explanations are far too technical.  While that technical detail
     needs to be there, there should also be a very basic laymans explanation.

99 - careful review of threads and ahelps by scientists.

102 - More up-to date informations. There seems to be a long lag
      between a "corridor rumor" on a problem/correction and the official
      announcement. 

      We should not have to ask a question to get a (late) answer that
      says "Oh, this is a well known problem" when this "known problem" is
      nowhere described...

103 - the threads need to evolve to include more complex data analysis situations.

105 - I do not know.

106 - I'd like to see a more detailed thread on extracting and fitting
      radial profiles, including the use of an exposure map, and comparing
      profiles of a source with the psf to see if it is extended.

108 - more examples of common cases

111 - information on importance of corrections, e.g. CTI corrections...

113 - Consequences for data analysis of improvements in calibration

119 - add more threads, also on "basic" topics.
      Maybe it could be useful to collect them in a "how-to handbook"

124 - Scripts are often poorly documented (I mean the script code itself).
      There is little indication of what the steps are, and why things are
      being done.  Also, scripts do not replace the need for step-by-step
      threads for what the script is doing.  I don't want a black box,
      I want to know precisely what it is doing to my data.  So, in general,
      I usually end up looking at the script, figuring out what it's up to,
      and writing my own with documentation of the steps, additional logging
      information, substituting tools with funtools or ftools, etc.

126 - The ahelp pages often lack information explaining all of the
      options for each keyword in the call sequence.