Annotator 2.0 Documentation Planning

Date: January 22, 2014

Attendees: Nick Stenning, Andrew Magliozzi, Jamie Folsom, Doug Schepers, Dan Whaley, Randall Leeds, Jake Hartnell, et. al.



  • Update the agenda
  • Discussion
  • Assign Todos


  • Process for writing docs (Nick and Randall?)
  • How is the documentation generated? [a]
  • What aspects of the Annotator API docs need updating?
  • Plain english documentation about how how it works and how pieces work together.
  • Which other docs can we model? [see “Docs we like” below]
  • How will we handle new storage and auth?
  • Most hasn’t changed… names have changed a little as has plugin loading.  Authentication hasn’t changed yet and may not change before 2.0.
  • How can we make the Annotator landing page better?
  • What will developers need to know about Annotator 2.0?
  • Question: GH-Pages branch, or Wiki? Pros/Cons?
  • use HG-Pages branch
  • Who should write the Outline/TOC?
  • Should we use to annotate the current docs?
  • Create a account by downloading the Chrome extension at:
  • And following the directions on the page
  • I Annotate 2014, Apr 3-4, Hack days Apr 5-6

Action Items

  • @Nick - on the docs
  • @Nick - Import “reStructuredText - how does it work?” meta-documentation
  • Create a Docs branch
  • @Michael,Jamie - Review documentation for sanity, up-to-date-ness
  • @AndrewM - Update links -- remove wiki markup and replace with rST links
  • @Nick - Remove all reference to AnnotateIt from docs
  • @Dan - Collect Annotator use-cases and demos
  • [thanks for starting this already, @DanWhaley!!]
  • DONE @Nick,Andrew - set up[b] to point to gh-pages
  • @AndrewB - Create desired sitemap[c]
  • @AndrewM - update github pages content (switch to Jekyll)
  • @Jake,Randall - Update appearance
  • DONE @Nick,AndrewM - -- point at RTD
  • @Randall - API docs extraction
  • DONE @Nick - Remove documentation from wiki and update to point to
  • can we migrate our google doc to our community / annotator-in-the-wild page?
  • showcase projects with a page like this:
  • Find and list existing Annotator plugins
  • Create
  • Where does annotator “live”? OKFN?
  • Assemble FAQs from the mailing list
  • Make an Annotator setup tutorial (screencast / gist / etc)

Docs we like:

[a]Good question. I think we need documentor documentation. Short answer for you: "pip install sphinx && cd doc/ && make html"


[c]Here's a draft: