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