Hi, for drafting and discussing stuff, Google Docs is a great thing.
But actual documentation, should IMHO be in a diff-friendly format in the repository. I've grown quite fond of asciidoctor which can generate nice HTML and PDF documents without the horrendous overhead and complexity of Docbook XML. Also, these days Eclipse by default comes with a basic "preview" support for Asciidoc. These here are generated using Asciidoctor: - https://webanno.github.io/webanno/releases/3.2.2/docs/user-guide.html - https://webanno.github.io/webanno/releases/3.2.2/docs/user-guide.pdf The sources for these documents are here: https://github.com/webanno/webanno/tree/master/webanno-doc The DKPro Core documentation is also done using Asciidoc. However, here most of the documentation is actually autogenerated by aggregating information from different sources (UIMA descriptors, JavaDoc, etc.) and generating asciidoc source files from them which are then finally rendered into HTML. https://dkpro.github.io/dkpro-core/releases/1.8.0/docs/component-reference.html The dynamic TOC on the side is done using tocify. Cheers, -- Richard > On 16.08.2017, at 15:34, Marshall Schor <[email protected]> wrote: > > Hi, > > I want/need to create a nice doc, with diagrams, etc., together with other > interested parties in our community. > > The particular doc driving this is one related to UIMA-5536, and is around the > subtleties and design-for-least-surprise notions, involved with iterators and > indexes without type priorities. > > I thought it would be nice to be able to collaboratively edit such a doc, > rather > than just having long email chains. It seems google docs might fit the > needs, well. > > At some point, I suppose we could consider using google docs for actual > documentation work, too. There are ways to export and import (for example to > microsoft word), where we could have some kind of official "source" in svn. > There are ways to create PDFs, and web-page formats, too. And there is an > extensive permissions system. > > WDYT? > > -Marshall
