You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@nifi.apache.org by Mark Payne <ma...@hotmail.com> on 2014/12/17 20:24:40 UTC
User Guide
All,
I have started work on a NiFi User Guide (https://issues.apache.org/jira/browse/NIFI-150). There is a lot of work to be done here for sure, and I've only really started. However, what I've written up so far may be useful to those of you who haven't had a chance to learn NiFi yet. General terminology is described, some of the icons are explained, etc.
So far I've been writing it Open Office. I don't know if this is the format that we want to stick with, but that can easily be changed later. It is checked into the NIFI-USER-GUIDE branch, under nar-bundles/framework-bundle/framework/resources/src/main/resources/docs. I expect to be adding quite a bit to this in the coming days.
Thanks-Mark
Re: User Guide
Posted by Joe Witt <jo...@gmail.com>.
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 <ma...@hotmail.com> 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 <ad...@adamtaft.com> 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 <ma...@hotmail.com>
> 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: joe.witt@gmail.com
> >>> To: dev@nifi.incubator.apache.org
> >>>
> >>> 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 <
> >> billie.rinaldi@gmail.com>
> >>> 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 <jo...@gmail.com>
> 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 <an...@andyic.org>
> >>>>> 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
> >>
> >>
>
Re: User Guide
Posted by Mark Payne <ma...@hotmail.com>.
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 <ad...@adamtaft.com> 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 <ma...@hotmail.com> 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: joe.witt@gmail.com
>>> To: dev@nifi.incubator.apache.org
>>>
>>> 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 <
>> billie.rinaldi@gmail.com>
>>> 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 <jo...@gmail.com> 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 <an...@andyic.org>
>>>>> 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
>>
>>
Re: User Guide
Posted by Adam Taft <ad...@adamtaft.com>.
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 <ma...@hotmail.com> 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: joe.witt@gmail.com
> > To: dev@nifi.incubator.apache.org
> >
> > 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 <
> billie.rinaldi@gmail.com>
> > 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 <jo...@gmail.com> 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 <an...@andyic.org>
> > > > 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
> > > > >
> > > >
> > >
>
>
RE: User Guide
Posted by Mark Payne <ma...@hotmail.com>.
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: joe.witt@gmail.com
> To: dev@nifi.incubator.apache.org
>
> 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 <bi...@gmail.com>
> 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 <jo...@gmail.com> 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 <an...@andyic.org>
> > > 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
> > > >
> > >
> >
Re: User Guide
Posted by Joe Witt <jo...@gmail.com>.
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 <bi...@gmail.com>
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 <jo...@gmail.com> 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 <an...@andyic.org>
> > 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
> > >
> >
>
Re: User Guide
Posted by Billie Rinaldi <bi...@gmail.com>.
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 <jo...@gmail.com> 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 <an...@andyic.org>
> 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
> >
>
Re: User Guide
Posted by Joe Witt <jo...@gmail.com>.
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 <an...@andyic.org> 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
>
Re: User Guide
Posted by Andy Christianson <an...@andyic.org>.
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
Re: User Guide
Posted by Joe Witt <jo...@gmail.com>.
I agree the source control 'friendliness' is an important consideration.
Once we have multiple active authors contributing documentation it becomes
really important. The current lack of documentation though is critical.
We can go from any format to any format but we can't convert nothing to
something. So in that spirit am grateful to whomever gets the
documentation party started however they are willing to.
Thanks
Joe
On Wed, Dec 17, 2014 at 4:30 PM, Mark Payne <ma...@hotmail.com> wrote:
>
> I definitely see the benefit of having the Git-tracking friendliness.
> Though I'm not convinced that the benefit outweighs the cost. At this point
> I'd much prefer a format that provides a fully featured word processing
> capability over any markup format for a document this extensive...
>
> Sent from my iPhone
>
> > On Dec 17, 2014, at 4:10 PM, Karl Heinz Marbaise <kh...@gmx.de>
> wrote:
> >
> > Hi Tony,
> >
> > to be honest I'm using LaTeX for a very long time (ca. 20 years) which
> is great but i have started to use asciidoc for a longer time (about a
> year) and it's much simpler to learn to understand and to use it with VCS
> etc.
> >
> > Furthermore I have started to use markdown for my blog for about two
> years which makes it simpler using the things in Git etc.
> >
> > From asciidoc you can create every kind out of the format from it like
> LaTeX from it...HTML / XML etc.
> >
> > I have to say LaTeX has some advantages which do not really count
> here...the KISS principle is here the key..there a big differences between
> asciidoc/markdown and LaTeX ...
> >
> >
> > so i would definitely vote for asciidoc or markdown...
> >
> >
> > for Markdow an doxia converter exists...but this should prevent from
> using asciidoc...might be chance to push support asciidoc in Maven..but
> this is a different story...
> >
> >
> > Kind regards
> > Karl Heinz Marbaise
> >
> >> On 12/17/14 8:58 PM, Tony Kurc wrote:
> >> Or LaTex [1]. Same advantages.
> >>
> >> [1] http://www.latex-project.org/
> >>
> >>> On Wed, Dec 17, 2014 at 2:38 PM, Adam Taft <ad...@adamtaft.com> wrote:
> >>>
> >>> Would highly recommend writing the user guide in asciidoc. It can
> then be
> >>> easily contributed/merged, etc. using normal text editing + git tools.
> >>>
> >>> Pro Git, 2nd Ed. is written in Asciidoc, as an example.
> >>>
> >>>
> >>>
> https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
> >>>
> >>> Here is the git repository associated with the book:
> >>>
> >>> https://github.com/progit/progit2
> >>>
> >>>
> >>>
> >>>
> >>>
> >>>
> >>>> On Wed, Dec 17, 2014 at 2:24 PM, Mark Payne <ma...@hotmail.com>
> wrote:
> >>>>
> >>>> All,
> >>>> I have started work on a NiFi User Guide (
> >>>> https://issues.apache.org/jira/browse/NIFI-150). There is a lot of
> work
> >>>> to be done here for sure, and I've only really started. However, what
> >>> I've
> >>>> written up so far may be useful to those of you who haven't had a
> chance
> >>> to
> >>>> learn NiFi yet. General terminology is described, some of the icons
> are
> >>>> explained, etc.
> >>>> So far I've been writing it Open Office. I don't know if this is the
> >>>> format that we want to stick with, but that can easily be changed
> later.
> >>> It
> >>>> is checked into the NIFI-USER-GUIDE branch, under
> >>>
> nar-bundles/framework-bundle/framework/resources/src/main/resources/docs. I
> >>>> expect to be adding quite a bit to this in the coming days.
> >>>> Thanks-Mark
> >>>>
> >>>>
>
Re: User Guide
Posted by Mark Payne <ma...@hotmail.com>.
I definitely see the benefit of having the Git-tracking friendliness. Though I'm not convinced that the benefit outweighs the cost. At this point I'd much prefer a format that provides a fully featured word processing capability over any markup format for a document this extensive...
Sent from my iPhone
> On Dec 17, 2014, at 4:10 PM, Karl Heinz Marbaise <kh...@gmx.de> wrote:
>
> Hi Tony,
>
> to be honest I'm using LaTeX for a very long time (ca. 20 years) which is great but i have started to use asciidoc for a longer time (about a year) and it's much simpler to learn to understand and to use it with VCS etc.
>
> Furthermore I have started to use markdown for my blog for about two years which makes it simpler using the things in Git etc.
>
> From asciidoc you can create every kind out of the format from it like LaTeX from it...HTML / XML etc.
>
> I have to say LaTeX has some advantages which do not really count here...the KISS principle is here the key..there a big differences between asciidoc/markdown and LaTeX ...
>
>
> so i would definitely vote for asciidoc or markdown...
>
>
> for Markdow an doxia converter exists...but this should prevent from using asciidoc...might be chance to push support asciidoc in Maven..but this is a different story...
>
>
> Kind regards
> Karl Heinz Marbaise
>
>> On 12/17/14 8:58 PM, Tony Kurc wrote:
>> Or LaTex [1]. Same advantages.
>>
>> [1] http://www.latex-project.org/
>>
>>> On Wed, Dec 17, 2014 at 2:38 PM, Adam Taft <ad...@adamtaft.com> wrote:
>>>
>>> Would highly recommend writing the user guide in asciidoc. It can then be
>>> easily contributed/merged, etc. using normal text editing + git tools.
>>>
>>> Pro Git, 2nd Ed. is written in Asciidoc, as an example.
>>>
>>>
>>> https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
>>>
>>> Here is the git repository associated with the book:
>>>
>>> https://github.com/progit/progit2
>>>
>>>
>>>
>>>
>>>
>>>
>>>> On Wed, Dec 17, 2014 at 2:24 PM, Mark Payne <ma...@hotmail.com> wrote:
>>>>
>>>> All,
>>>> I have started work on a NiFi User Guide (
>>>> https://issues.apache.org/jira/browse/NIFI-150). There is a lot of work
>>>> to be done here for sure, and I've only really started. However, what
>>> I've
>>>> written up so far may be useful to those of you who haven't had a chance
>>> to
>>>> learn NiFi yet. General terminology is described, some of the icons are
>>>> explained, etc.
>>>> So far I've been writing it Open Office. I don't know if this is the
>>>> format that we want to stick with, but that can easily be changed later.
>>> It
>>>> is checked into the NIFI-USER-GUIDE branch, under
>>> nar-bundles/framework-bundle/framework/resources/src/main/resources/docs. I
>>>> expect to be adding quite a bit to this in the coming days.
>>>> Thanks-Mark
>>>>
>>>>
Re: User Guide
Posted by Karl Heinz Marbaise <kh...@gmx.de>.
Hi Tony,
to be honest I'm using LaTeX for a very long time (ca. 20 years) which
is great but i have started to use asciidoc for a longer time (about a
year) and it's much simpler to learn to understand and to use it with
VCS etc.
Furthermore I have started to use markdown for my blog for about two
years which makes it simpler using the things in Git etc.
From asciidoc you can create every kind out of the format from it like
LaTeX from it...HTML / XML etc.
I have to say LaTeX has some advantages which do not really count
here...the KISS principle is here the key..there a big differences
between asciidoc/markdown and LaTeX ...
so i would definitely vote for asciidoc or markdown...
for Markdow an doxia converter exists...but this should prevent from
using asciidoc...might be chance to push support asciidoc in Maven..but
this is a different story...
Kind regards
Karl Heinz Marbaise
On 12/17/14 8:58 PM, Tony Kurc wrote:
> Or LaTex [1]. Same advantages.
>
> [1] http://www.latex-project.org/
>
> On Wed, Dec 17, 2014 at 2:38 PM, Adam Taft <ad...@adamtaft.com> wrote:
>>
>> Would highly recommend writing the user guide in asciidoc. It can then be
>> easily contributed/merged, etc. using normal text editing + git tools.
>>
>> Pro Git, 2nd Ed. is written in Asciidoc, as an example.
>>
>>
>> https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
>>
>> Here is the git repository associated with the book:
>>
>> https://github.com/progit/progit2
>>
>>
>>
>>
>>
>>
>> On Wed, Dec 17, 2014 at 2:24 PM, Mark Payne <ma...@hotmail.com> wrote:
>>>
>>> All,
>>> I have started work on a NiFi User Guide (
>>> https://issues.apache.org/jira/browse/NIFI-150). There is a lot of work
>>> to be done here for sure, and I've only really started. However, what
>> I've
>>> written up so far may be useful to those of you who haven't had a chance
>> to
>>> learn NiFi yet. General terminology is described, some of the icons are
>>> explained, etc.
>>> So far I've been writing it Open Office. I don't know if this is the
>>> format that we want to stick with, but that can easily be changed later.
>> It
>>> is checked into the NIFI-USER-GUIDE branch, under
>>>
>> nar-bundles/framework-bundle/framework/resources/src/main/resources/docs. I
>>> expect to be adding quite a bit to this in the coming days.
>>> Thanks-Mark
>>>
>>>
Re: User Guide
Posted by Sean Busbey <bu...@cloudera.com>.
+1 asciidoc.
really, any of the asciidoc, docbook, markdown will get you a much easier
learning curve for new contributors than alternatives.
On Wed, Dec 17, 2014 at 1:58 PM, Tony Kurc <tr...@gmail.com> wrote:
> Or LaTex [1]. Same advantages.
>
> [1] http://www.latex-project.org/
>
> On Wed, Dec 17, 2014 at 2:38 PM, Adam Taft <ad...@adamtaft.com> wrote:
> >
> > Would highly recommend writing the user guide in asciidoc. It can then
> be
> > easily contributed/merged, etc. using normal text editing + git tools.
> >
> > Pro Git, 2nd Ed. is written in Asciidoc, as an example.
> >
> >
> >
> https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
> >
> > Here is the git repository associated with the book:
> >
> > https://github.com/progit/progit2
> >
> >
> >
> >
> >
> >
> > On Wed, Dec 17, 2014 at 2:24 PM, Mark Payne <ma...@hotmail.com>
> wrote:
> > >
> > > All,
> > > I have started work on a NiFi User Guide (
> > > https://issues.apache.org/jira/browse/NIFI-150). There is a lot of
> work
> > > to be done here for sure, and I've only really started. However, what
> > I've
> > > written up so far may be useful to those of you who haven't had a
> chance
> > to
> > > learn NiFi yet. General terminology is described, some of the icons are
> > > explained, etc.
> > > So far I've been writing it Open Office. I don't know if this is the
> > > format that we want to stick with, but that can easily be changed
> later.
> > It
> > > is checked into the NIFI-USER-GUIDE branch, under
> > >
> >
> nar-bundles/framework-bundle/framework/resources/src/main/resources/docs. I
> > > expect to be adding quite a bit to this in the coming days.
> > > Thanks-Mark
> > >
> > >
> > >
> >
>
--
Sean
Re: User Guide
Posted by Tony Kurc <tr...@gmail.com>.
Or LaTex [1]. Same advantages.
[1] http://www.latex-project.org/
On Wed, Dec 17, 2014 at 2:38 PM, Adam Taft <ad...@adamtaft.com> wrote:
>
> Would highly recommend writing the user guide in asciidoc. It can then be
> easily contributed/merged, etc. using normal text editing + git tools.
>
> Pro Git, 2nd Ed. is written in Asciidoc, as an example.
>
>
> https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
>
> Here is the git repository associated with the book:
>
> https://github.com/progit/progit2
>
>
>
>
>
>
> On Wed, Dec 17, 2014 at 2:24 PM, Mark Payne <ma...@hotmail.com> wrote:
> >
> > All,
> > I have started work on a NiFi User Guide (
> > https://issues.apache.org/jira/browse/NIFI-150). There is a lot of work
> > to be done here for sure, and I've only really started. However, what
> I've
> > written up so far may be useful to those of you who haven't had a chance
> to
> > learn NiFi yet. General terminology is described, some of the icons are
> > explained, etc.
> > So far I've been writing it Open Office. I don't know if this is the
> > format that we want to stick with, but that can easily be changed later.
> It
> > is checked into the NIFI-USER-GUIDE branch, under
> >
> nar-bundles/framework-bundle/framework/resources/src/main/resources/docs. I
> > expect to be adding quite a bit to this in the coming days.
> > Thanks-Mark
> >
> >
> >
>
Re: User Guide
Posted by Adam Taft <ad...@adamtaft.com>.
Would highly recommend writing the user guide in asciidoc. It can then be
easily contributed/merged, etc. using normal text editing + git tools.
Pro Git, 2nd Ed. is written in Asciidoc, as an example.
https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
Here is the git repository associated with the book:
https://github.com/progit/progit2
On Wed, Dec 17, 2014 at 2:24 PM, Mark Payne <ma...@hotmail.com> wrote:
>
> All,
> I have started work on a NiFi User Guide (
> https://issues.apache.org/jira/browse/NIFI-150). There is a lot of work
> to be done here for sure, and I've only really started. However, what I've
> written up so far may be useful to those of you who haven't had a chance to
> learn NiFi yet. General terminology is described, some of the icons are
> explained, etc.
> So far I've been writing it Open Office. I don't know if this is the
> format that we want to stick with, but that can easily be changed later. It
> is checked into the NIFI-USER-GUIDE branch, under
> nar-bundles/framework-bundle/framework/resources/src/main/resources/docs. I
> expect to be adding quite a bit to this in the coming days.
> Thanks-Mark
>
>
>