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 > > >
