You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@annotator.apache.org by "J. S. Choi" <js...@icloud.com> on 2017/05/11 15:14:03 UTC

Updating subsumed/related projects’ documentation

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

Re: Updating subsumed/related projects’ documentation

Posted by Randall Leeds <ra...@apache.org>.
On Sun, May 14, 2017, 02:08 Kiffin Gish <ki...@gmail.com> wrote:

> Hi there.
>
> I'm also confused by the slight disarray of available annotation
> solutions out there.
>

Hopefully, our efforts here can provide a path towards some unification and
organization.


> While annotatorjs might be slightly outdated, it still suites my needs
> and the documentation is very nice. For me at least it's the best
> implementation.
>

That's great to hear.

If you or anyone else using it would like to see changes, I'm happy review
pull requests. I'm not sufficient motivated to make any major improvements
to it, though.



> You refer to the ApAnn implementation, but I cannot seem to find any
> information about it on the web. Could you please provide a link?
>

I believe that's short for Apache Annotator, the subject of this mailing
list.

https://annotator.apache.org

Re: Updating subsumed/related projects’ documentation

Posted by Kiffin Gish <ki...@gmail.com>.
Hi there.

I'm also confused by the slight disarray of available annotation 
solutions out there.

While annotatorjs might be slightly outdated, it still suites my needs 
and the documentation is very nice. For me at least it's the best 
implementation.

You refer to the ApAnn implementation, but I cannot seem to find any 
information about it on the web. Could you please provide a link?

Regards,

Kiffin


On 05/11/2017 05:14 PM, "J. S. Choi" wrote:
> 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
>
>
>
>
>

-- 
Kiffin Gish
Gouda, The Netherlands