Mark, Adam, I'd say you should start a jira ticket for this concept and place both ideas onto it.
Thanks Joe On Thu, Dec 18, 2014 at 7:06 PM, Mark Payne <[email protected]> wrote: > > Adam, > > Matt and I were discussing this today. It will require a significant > amount of thought before we go all in because we have also been talking > about Auto-Generating all of this info from annotations, etc. perhaps all > additional docs to enrich that though. > > We haven't created any JIRA tickets because we haven't thought through it > all yet. Could create a ticket to "consider" doing it though so we can add > Comments and document all of our thoughts and solicit thoughts from others. > > Sent from my iPhone > > > On Dec 18, 2014, at 7:01 PM, Adam Taft <[email protected]> wrote: > > > > Now for bonus points... > > > > It would be a really nice to have all of the "/niagarafiles-docs/" (i.e. > > "Usage") processor documentation also written in asciidoc (instead of > > copy/paste HTML). We get all the bonuses, including consistent styling, > > simple editing, alternative formats (PDF), etc. > > > > The nifi-docs servlet could dynamically generate HTML from the asciidoc > > source, or the asciidoc could be compiled at build time into various > output > > formats. I think a single PDF of the entire "marketplace" documentation > > could be possible with this approach. This is important so that we don't > > have to necessarily host the marketplace docs like we do today (i.e. > with a > > .php script). > > > > Want me to file a JIRA ticket? > > > > Adam > > > > p.s. if we do this, it's possibly ideal to have the processor > documentation > > distributed outside of the processor classpath. I think there might be > > some benefits to maintaining the processor specific documentation outside > > of the src/main/resources directory structure of each jar. Instead, we'd > > build a single (zip?) file that includes all the documentation in one > > place. Easier this way to create single coherent document books, like a > > PDF of all processor marketplace descriptions. Something to ponder. > > > > > > > >> On Thu, Dec 18, 2014 at 4:16 PM, Mark Payne <[email protected]> > wrote: > >> > >> 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 > >> > >> >
