[annotator-dev] Annotator documentation: how to write good documentation

Wed Jan 22 19:02:31 UTC 2014

Dear all,

Some of you will have been on the call we had this afternoon to discuss
improving Annotator's documentation. We now have a "working group" who
are volunteering to improve the state of Annotator documentation, and we
already have draft documentation up at http://annotator.readthedocs.org.

> HEALTH WARNING: the docs are not currently:
>  - up-to-date
>  - fully functional (some wiki markup remains)
>  - at their final location (they will likely move to https://docs.annotatorjs.org soon)

That said, I thought it would be really useful to circulate a few links
to get people thinking about the role of documentation, and how to write
good documentation.

Some great introductory documentation (!) on writing documentation: 

  http://docs.writethedocs.org/

The talk that inspired the "write the docs" movement: 

  http://pyvideo.org/video/1795/write-the-docs

Django's Jacob Kaplan-Moss on writing good docs: 

  http://jacobian.org/writing/great-documentation/

Jacob talking about great documentation: 

  http://pyvideo.org/video/403/pycon-2011--writing-great-documentation

Lastly, if the above has sufficiently inspired you, I will point to
Annotator's documentation source, on GitHub:

  https://github.com/okfn/annotator/tree/master/doc

Best,
Nick