Problems in the annotation doc

Dear WinWriters,

I just looked at the documentation rewrite for the Annotations. I was
surprised to find that the documentation corrections was not just
a rewrite of English. In some cases, they are important obmissions and
technical errors. You'll find the detailed list here below.

- The HTML of the pages is invalid. Sometimes there are '<' characters
  or unknown attributes.  It is important that the pages that we are 
  distributing are valid. The previous documentation was valid. The new
  one should be so too. You can use the validator to help you[1].

- I also want to remind you that URLs of this type are invalid:
	href="..\something\"

  In a URL, there should be no '\' character. Just '/'. That can then be
  converted into the local system one. 

- The main index of the Annotation doc is now given in alphabetical order.
  Could you restore the order I had given in the previous documentation?
  That order was a logical order explaining what was an annotation, how
  to use them, up to the problems. The alphabetical order is correct for the
  main index but it doesn't make the documentation more useful in this
  section. 

- In the "Known Issues with Annotations and Modified Documents" section, 
  you removed all the examples I had given. Could you please insert them back
  or justify why they were removed?  The example is much more clearer than a
  word explanation. That's why it was there from the beginning.

  In this same section, please put style (boldface or whatever is 
  appropriate) around the following terms: orphan annotation, misleading
  annotation.

- You removed the section that describes what is an annotation (first section
  of the old documentation). Can you add it back or explain why it was removed?
  It is important that that section remains there. Not everyone knows what
  is an annotation or they have different interpretations about it.

- In "About Storing local annotations", you're describing local annotations.
  Not how you save them. I propose you change this section title to
  "About Local Annotations".

- In "About Stored Annotations", the description has several errors:

  First of all, the title is miselading. We don't have any stored annotations.
  It should say "About Remote Annotations".

  Amaya can store annotation data in a local file system(often called "local 
  annotations") or it can store annotations remotely, accessed through the 
  World Wide Web (called "remote annotations").

  This sounds clearer with the following modifications:

  "system (which we refer to as "local annotations") or it can store
   annotations remotely, in Annotations Servers accessed through the World     
   Wide Web..."

  You can store remote annotations in annotation servers so that the 
  annotations can be downloaded and stored by anyone having the correct 
                                    ^^^^^
                                    modified

  access rights, such as is the case of other HTML documents. Remote 
  annotations are shared or public annotations, because they can be seen by 
  other people. If you wish to install your own annotation server, please
  refer to Annotation-Server-HOWTO.

  Please change to 
    "... We often to refer to remote annotations as shared or public 
  annotations, because..."

- In the section "Creating an Annotation", you supressed the images that
  give the example of how to annotate. Could you restore them or justify
  why they were removed?

- In the section "Deleting an annotation", your rewrite obmitted information.

  The new text says:

  "The Delete command on the Annotation menu enables you to delete an 
   annotation. You can invoke this command from an open annotation window.
   To delete an annotation from a document:
      Select the annotation by clicking the annotation icon. 
      Choose Delete from the Annotations menu.
  "

  This text only describes one way to delete annotations. There are actually
  two ways and the old text described them:

  "The Annotations/Delete menu command lets you delete an annotation. You can 
   invoke this command from an open annotation window . You can also delete  
   an annotation from the annotated document by first selecting the annotation 
   by doing a simple click on the annotation icon, and then calling this 
   menu command."

   Can you add the phrase that was obmitted or restore the original text?
   
- In the section "Loading and Presenting Annotations", there's an error
  in the text

  "Annotations can also be loaded into a new page by selecting the Autoload 
   Annotations check box in the Configuration for annotations dialog."

  This option means that the annotations will be loaded automatically 
  each time we browse a page. Your description is not clear enough.
  
  In comparition, here's the previous text which was clearer:

  "The annotations can also be loaded automatically whenever a new page is 
   loaded by selecting the Autoload annotations checkbox in the 
   Annotations/Configure dialogue."

- In the section "Moving Annotations", can you add a link to the "Annotation
  issues" section on the underlined words of the following phrase:

  You can move an annotation to any other part of the same document. This 
  can be used, for example, to handle orphan and misleading annotations. 
                                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  This was the case in the previous documentation.

- The title of section "Moving Multiple Annotations" is wrong. It should
  be "Moving Annotations to a Previously Memorized Location".

I will send you in a separate mail a new entry for the annotation
documentation.

Could you tell me if this changes will be ready for this release?

Thanks in advance,

-jose

Received on Thursday, 13 December 2001 05:14:47 UTC