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 >
