This is Joshua Choi; I’m a medical student with an interest in annotation, particularly in how biomedical annotation may help us physicians make better clinical decisions. It’s nice to meet you all. What you’re doing is exciting. During the iAnnotate 2017 hackathon, I discussed documentation with Mr. Young, Mr. Leeds, and Mr. Knight, and they invited me to make a post to this mailing list.
I believe that someone should update the documentation of the older annotation libraries that are related to ApAnn—particularly the ones subsumed by ApAnn. I’m volunteering to be that someone. There are numerous scattered older projects and websites related to Apache Annotator, yet giving out-of-date documentation. They are out of date because the Hot New, Vibrant, De-Facto-Standard, State-of-the-Art Implementation of Web/Open Annotations is ApAnn, and yet their documentation does not mention ApAnn. These older projects/websites include DOM-Anchor-Text-Quote, DOM-Anchor-Text-Position, DOM-Seek, DOM-Node-Iterator, Simple-XPath-Position, Hypothesis/H (both readme and Read the Docs), Hypothesis/Client, Hypothesis/Browser-Extension, OpenAnnotation/Annotator, AnnotatorJS.org <http://annotatorjs.org/>, OpenAnnotation/Annotator-Wordpress, XPath-Range, AnnotateIt, Annotator-Store, Annotator-TokenAuth, Annotator-AnnotateIt, http://hypothes.is/contribute/ <http://hypothes.is/contribute/>, https://www.w3.org/community/openannotation <https://www.w3.org/community/openannotation>, OpenAnnotation.org <http://openannotation.org/>, and http://openannotation.wordpress.com <http://openannotation.wordpress.com/>. What we have here are several disparate yet related projects, any of which people searching for “annotator”, “web annotation”, or “open annotation” might encounter at any time. Any of these, at any time, may be giving people their first impression of the whole web-annotation world. And many of them have been obsoleted or subsumed, appearing abandoned at a cursory glance. This is particularly relevant to ApAnn in that it is a new project that subsumes many other projects—particularly Mr. Leed’s projects and OpenAnnotation’s Annotator.js. Annotator.js alone has more than 1800 GitHub stars, underscoring its prominence and popularity. Any of the thousands of people who encounter Annotator.js may presume it to be the cutting edge of the open-annotation space. Yet it is obviously sessile, its last commit being in 2015. Because ApAnn is subsuming Annotator.js, the latter’s documentation (both readme and website) should be updated with a message at its beginning. The message might say something like (but not exactly): **This library is historical. It has been superseded by [Apache Annotator](http://annotator.apache.org <http://annotator.apache.org/>). See [Annotator’s FAQ](link to Robert Knight’s FAQ) for more information.** Or, for a library like Hypothesis’ client, this message might be added to the bottom of its readme: ## Relation to Apache Annotator This library is for use by a *specific* nonprofit service, [Hypothesis](http://hypothes.is <http://hypothes.is/>), as well as anyone using Hypothesis to store webpages. It uses **[Apache Annotator](http://annotator.apache.org <http://annotator.apache.org/>)** for its generic [Web Annotations](https://www.w3.org/community/openannotation/ <https://www.w3.org/blog/news/archives/6156>) functionality. I believe this is truly important. Most people who will need, use, or help with ApAnn will appear in the future, and they should be able to clearly and quickly understand that this is the Hot New and Vibrant Open-Annotation Implementation, without getting lost in old, abandoned projects as I had been for some time. Web Annotations might need all the clarity and publicity it can get. My next step would be to create a Confluence wiki/blog page on the Apache website with an outline of all the out-of-date documentation. I would then, during my free time, draft modifications to each out-of-date document. But before that, if anyone has any broad feedback regarding the plan, let me know. I plan to get properly started soon. Looking forward to working with you all, Joshua Choi Saint Louis University
