True story. I've put quite a bit of effort today into learning asciidoc and converting the Open Office document and writing additional documentation. Asciidoc comes with its own oddities and nuancies, etc., but I have been very impressed with it! Many thanks to all of the people who chimed in so adamantly - otherwise I probably would not have gone this route :) Will be checking in a new asciidoc version this afternoon. Thanks-Mark
> Date: Thu, 18 Dec 2014 13:15:46 -0500 > Subject: Re: User Guide > From: [email protected] > To: [email protected] > > I think it is safe to say several of us who didn't know asciidoc have now > seen the light. Very impressive. Output is great. Nicely integrated to > browser extensions and maven plugins. Mark hasn't shared it yet but i just > saw work he is doing to move to asciidoc and make it an automated part of > the build. Really nice and thanks all for pointing it out and providing > references. > > > > On Thu, Dec 18, 2014 at 1:11 PM, Billie Rinaldi <[email protected]> > wrote: > > > > I enjoy working with asciidoc. I tried both markdown and asciidoc for the > > Accumulo manual, and had a much easier time with the maven plugin for > > asciidoc (plus it seemed to have better features built in, like code > > highlighting). > > > > On Wed, Dec 17, 2014 at 7:36 PM, Joe Witt <[email protected]> wrote: > > > > > Mark > > > > > > First i think those initial 10 pages of docs you put together are a great > > > start. > > > > > > All, > > > > > > This link to me is an excellent example of documentation that begs to be > > > read and is frankly just really well done (the new ASF proposal today): > > > http://www.tinkerpop.com/docs/3.0.0-SNAPSHOT/ > > > > > > Written in asciidoc. > > > > > > So how can we integrate this nicely into the build process and produce > > > different types of outputs: > > > > > > https://github.com/asciidoctor/asciidoctor-maven-plugin > > > > > > This is pretty compelling provided we can make the experience of > > generating > > > the markup enjoyable/productive. > > > > > > Thanks > > > Joe > > > > > > On Wed, Dec 17, 2014 at 6:29 PM, Andy Christianson <[email protected]> > > > wrote: > > > > > > > > Have you all considered authoring in markdown and using pandoc to > > > generate > > > > the various output formats (html5, PDF, etc). Pandoc allows for the > > > > markdown to be extended with LaTeX as needed, and has good support for > > > > embedding generated graphics and such. I've worked on some large > > software > > > > projects using this technique and have had success with it. It takes > > some > > > > time to get it set up initially but after that, the documentation is > > very > > > > flexible and easy to edit. > > > > > > > > I'd be willing to help set up a maven build for this if you all are > > > > interested in doing it this way. > > > > > > > > I agree with the others that having an ASCII based format is pretty > > > > critical for working with others. Have you looked for a WYSIWYG > > markdown > > > > editor? I imagine one must exist. > > > > > > > > -Andy > > > > > > > > >
