[DISCUSS] Documentation Location

[Hans Van Akelyen <ha...@gmail.com>]

Hi All,

When we started this project we started with a separate documentation
repository [1].

While this seemed a great idea at the time I would like to come back to
this subject. I would like to propose to merge our documentation to our
source code repository.

There are three main advantages:
- Single source for releases
- Simpler testing
- More advanced asciidoc features

When creating a release we will automatically have a branch that contains
the documentation that is valid for that release, at this point in time
this is a non-issue as we are not yet creating versions of our
documentation and everything is still aligned, but when we move forward
parts of the documentation will become deprecated or linked to a specific
version.

If we single source our documentation we can include a basic version of our
documentation website to our code repository this will make it simpler to
see what the end result will look like. It allows you to do changes in an
adoc file and instantly see the new version in a browser the same way it
will be represented on the website.

Asciidoc has features where you can include snippets/classes/methods of
your source code in your documentation, they are dynamically linked. This
means that if the method changes the docs will be updated instantly. Though
we would have to test if these features work in our current setup this can
be a great addition to our developer documentation.

As always this mail is to gather feedback and your opinion on the matter
before we start changing things.

Cheers,
Hans

[1] https://github.com/apache/incubator-hop-docs

Re: [DISCUSS] Documentation Location

[fp...@apache.org]

Hi,

+1, I think it will be easier to sync the documentation with the source
code.

regards,

François
fpapon@apache.org

Le 10/04/2021 à 19:38, Bart Maertens a écrit :
> Hi Hans,
>
> Totally agree, this will increase the quality of the docs and will make it
> easier to write and test documentation.
> It'll be quite a bit of work, but should be done before rather than after
> 1.0 imho.
>
> Regards,
> Bart
>
> On Sat, Apr 10, 2021 at 6:56 PM Hans Van Akelyen <ha...@gmail.com>
> wrote:
>
>> Hi All,
>>
>> When we started this project we started with a separate documentation
>> repository [1].
>>
>> While this seemed a great idea at the time I would like to come back to
>> this subject. I would like to propose to merge our documentation to our
>> source code repository.
>>
>> There are three main advantages:
>> - Single source for releases
>> - Simpler testing
>> - More advanced asciidoc features
>>
>> When creating a release we will automatically have a branch that contains
>> the documentation that is valid for that release, at this point in time
>> this is a non-issue as we are not yet creating versions of our
>> documentation and everything is still aligned, but when we move forward
>> parts of the documentation will become deprecated or linked to a specific
>> version.
>>
>> If we single source our documentation we can include a basic version of our
>> documentation website to our code repository this will make it simpler to
>> see what the end result will look like. It allows you to do changes in an
>> adoc file and instantly see the new version in a browser the same way it
>> will be represented on the website.
>>
>> Asciidoc has features where you can include snippets/classes/methods of
>> your source code in your documentation, they are dynamically linked. This
>> means that if the method changes the docs will be updated instantly. Though
>> we would have to test if these features work in our current setup this can
>> be a great addition to our developer documentation.
>>
>> As always this mail is to gather feedback and your opinion on the matter
>> before we start changing things.
>>
>> Cheers,
>> Hans
>>
>> [1] https://github.com/apache/incubator-hop-docs
>>

Re: [DISCUSS] Documentation Location

[Bart Maertens <ba...@know.bi>]

Hi Hans,

Totally agree, this will increase the quality of the docs and will make it
easier to write and test documentation.
It'll be quite a bit of work, but should be done before rather than after
1.0 imho.

Regards,
Bart

On Sat, Apr 10, 2021 at 6:56 PM Hans Van Akelyen <ha...@gmail.com>
wrote:

> Hi All,
>
> When we started this project we started with a separate documentation
> repository [1].
>
> While this seemed a great idea at the time I would like to come back to
> this subject. I would like to propose to merge our documentation to our
> source code repository.
>
> There are three main advantages:
> - Single source for releases
> - Simpler testing
> - More advanced asciidoc features
>
> When creating a release we will automatically have a branch that contains
> the documentation that is valid for that release, at this point in time
> this is a non-issue as we are not yet creating versions of our
> documentation and everything is still aligned, but when we move forward
> parts of the documentation will become deprecated or linked to a specific
> version.
>
> If we single source our documentation we can include a basic version of our
> documentation website to our code repository this will make it simpler to
> see what the end result will look like. It allows you to do changes in an
> adoc file and instantly see the new version in a browser the same way it
> will be represented on the website.
>
> Asciidoc has features where you can include snippets/classes/methods of
> your source code in your documentation, they are dynamically linked. This
> means that if the method changes the docs will be updated instantly. Though
> we would have to test if these features work in our current setup this can
> be a great addition to our developer documentation.
>
> As always this mail is to gather feedback and your opinion on the matter
> before we start changing things.
>
> Cheers,
> Hans
>
> [1] https://github.com/apache/incubator-hop-docs
>

Re: [DISCUSS] Documentation Location

[Hans Van Akelyen <ha...@gmail.com>]

Hi All,

This mail is to inform you all that the documentation has been moved and is
now included in the main repository.
The builds have been adjusted accordingly to pick up the documentation from
the new location.

All plugin documentation that was included in the code repository has also
been moved to its new location.

Writing docs should now be less of a hassle and linked to their release
version, a live preview mode has also been added, we will clean up the
instructions on how to contribute and work on our documentation in the
following days.

Cheers,
Hans


On Tue, 13 Apr 2021 at 10:45, Hans Van Akelyen <ha...@gmail.com>
wrote:

> Hi All,
>
> Thanks for the feedback, let's proceed in this direction.
>
> Cheers,
> Hans
>
> On Mon, 12 Apr 2021 at 18:52, Sergio Ramazzina <
> sergio.ramazzina@serasoft.it> wrote:
>
>> +1 for me too. Much easier to be maintained.
>>
>> Sergio Ramazzina
>> Sent from my iPhone
>>
>> > Il giorno 10 apr 2021, alle ore 18:56, Hans Van Akelyen <
>> hans.van.akelyen@gmail.com> ha scritto:
>> >
>> > Hi All,
>> >
>> > When we started this project we started with a separate documentation
>> > repository [1].
>> >
>> > While this seemed a great idea at the time I would like to come back to
>> > this subject. I would like to propose to merge our documentation to our
>> > source code repository.
>> >
>> > There are three main advantages:
>> > - Single source for releases
>> > - Simpler testing
>> > - More advanced asciidoc features
>> >
>> > When creating a release we will automatically have a branch that
>> contains
>> > the documentation that is valid for that release, at this point in time
>> > this is a non-issue as we are not yet creating versions of our
>> > documentation and everything is still aligned, but when we move forward
>> > parts of the documentation will become deprecated or linked to a
>> specific
>> > version.
>> >
>> > If we single source our documentation we can include a basic version of
>> our
>> > documentation website to our code repository this will make it simpler
>> to
>> > see what the end result will look like. It allows you to do changes in
>> an
>> > adoc file and instantly see the new version in a browser the same way it
>> > will be represented on the website.
>> >
>> > Asciidoc has features where you can include snippets/classes/methods of
>> > your source code in your documentation, they are dynamically linked.
>> This
>> > means that if the method changes the docs will be updated instantly.
>> Though
>> > we would have to test if these features work in our current setup this
>> can
>> > be a great addition to our developer documentation.
>> >
>> > As always this mail is to gather feedback and your opinion on the matter
>> > before we start changing things.
>> >
>> > Cheers,
>> > Hans
>> >
>> > [1] https://github.com/apache/incubator-hop-docs
>>
>

Re: [DISCUSS] Documentation Location

[Hans Van Akelyen <ha...@gmail.com>]

Hi All,

Thanks for the feedback, let's proceed in this direction.

Cheers,
Hans

On Mon, 12 Apr 2021 at 18:52, Sergio Ramazzina <se...@serasoft.it>
wrote:

> +1 for me too. Much easier to be maintained.
>
> Sergio Ramazzina
> Sent from my iPhone
>
> > Il giorno 10 apr 2021, alle ore 18:56, Hans Van Akelyen <
> hans.van.akelyen@gmail.com> ha scritto:
> >
> > Hi All,
> >
> > When we started this project we started with a separate documentation
> > repository [1].
> >
> > While this seemed a great idea at the time I would like to come back to
> > this subject. I would like to propose to merge our documentation to our
> > source code repository.
> >
> > There are three main advantages:
> > - Single source for releases
> > - Simpler testing
> > - More advanced asciidoc features
> >
> > When creating a release we will automatically have a branch that contains
> > the documentation that is valid for that release, at this point in time
> > this is a non-issue as we are not yet creating versions of our
> > documentation and everything is still aligned, but when we move forward
> > parts of the documentation will become deprecated or linked to a specific
> > version.
> >
> > If we single source our documentation we can include a basic version of
> our
> > documentation website to our code repository this will make it simpler to
> > see what the end result will look like. It allows you to do changes in an
> > adoc file and instantly see the new version in a browser the same way it
> > will be represented on the website.
> >
> > Asciidoc has features where you can include snippets/classes/methods of
> > your source code in your documentation, they are dynamically linked. This
> > means that if the method changes the docs will be updated instantly.
> Though
> > we would have to test if these features work in our current setup this
> can
> > be a great addition to our developer documentation.
> >
> > As always this mail is to gather feedback and your opinion on the matter
> > before we start changing things.
> >
> > Cheers,
> > Hans
> >
> > [1] https://github.com/apache/incubator-hop-docs
>

Re: [DISCUSS] Documentation Location

[Sergio Ramazzina <se...@serasoft.it>]

+1 for me too. Much easier to be maintained.

Sergio Ramazzina
Sent from my iPhone

> Il giorno 10 apr 2021, alle ore 18:56, Hans Van Akelyen <ha...@gmail.com> ha scritto:
> 
> Hi All,
> 
> When we started this project we started with a separate documentation
> repository [1].
> 
> While this seemed a great idea at the time I would like to come back to
> this subject. I would like to propose to merge our documentation to our
> source code repository.
> 
> There are three main advantages:
> - Single source for releases
> - Simpler testing
> - More advanced asciidoc features
> 
> When creating a release we will automatically have a branch that contains
> the documentation that is valid for that release, at this point in time
> this is a non-issue as we are not yet creating versions of our
> documentation and everything is still aligned, but when we move forward
> parts of the documentation will become deprecated or linked to a specific
> version.
> 
> If we single source our documentation we can include a basic version of our
> documentation website to our code repository this will make it simpler to
> see what the end result will look like. It allows you to do changes in an
> adoc file and instantly see the new version in a browser the same way it
> will be represented on the website.
> 
> Asciidoc has features where you can include snippets/classes/methods of
> your source code in your documentation, they are dynamically linked. This
> means that if the method changes the docs will be updated instantly. Though
> we would have to test if these features work in our current setup this can
> be a great addition to our developer documentation.
> 
> As always this mail is to gather feedback and your opinion on the matter
> before we start changing things.
> 
> Cheers,
> Hans
> 
> [1] https://github.com/apache/incubator-hop-docs

Re: [DISCUSS] Documentation Location

[Kevin Ratnasekera <dj...@gmail.com>]

+1

On Mon, Apr 12, 2021 at 11:13 AM Hiromu Hota <hi...@gmail.com> wrote:

> +1. Mono-repo-> easier to manage.
>
> Thanks,
> Hiromu
>
> On Sun, Apr 11, 2021 at 8:52 PM Brandon Jackson <us...@gmail.com>
> wrote:
>
> > I like this idea too.  +1 from me.
> >
> > Brandon
> >
> > On Sun, Apr 11, 2021 at 12:53 PM Matt Casters
> > <ma...@neo4j.com.invalid> wrote:
> >
> > > +1 from me as well Hans.  It's a great idea.  Sometimes I think it's
> > better
> > > to just do the work in the short term to avoid the accumulated pain
> over
> > > time.
> > > I certainly didn't have a lot of fun updating docs in the source code
> > > (plugin information) along with their navigation and index pages in the
> > > docs and so on.
> > > What you propose would solve most of the issues I was having.
> > > Cheers,
> > > Matt
> > >
> > > On Sat, Apr 10, 2021 at 6:56 PM Hans Van Akelyen <
> > > hans.van.akelyen@gmail.com>
> > > wrote:
> > >
> > > > Hi All,
> > > >
> > > > When we started this project we started with a separate documentation
> > > > repository [1].
> > > >
> > > > While this seemed a great idea at the time I would like to come back
> to
> > > > this subject. I would like to propose to merge our documentation to
> our
> > > > source code repository.
> > > >
> > > > There are three main advantages:
> > > > - Single source for releases
> > > > - Simpler testing
> > > > - More advanced asciidoc features
> > > >
> > > > When creating a release we will automatically have a branch that
> > contains
> > > > the documentation that is valid for that release, at this point in
> time
> > > > this is a non-issue as we are not yet creating versions of our
> > > > documentation and everything is still aligned, but when we move
> forward
> > > > parts of the documentation will become deprecated or linked to a
> > specific
> > > > version.
> > > >
> > > > If we single source our documentation we can include a basic version
> of
> > > our
> > > > documentation website to our code repository this will make it
> simpler
> > to
> > > > see what the end result will look like. It allows you to do changes
> in
> > an
> > > > adoc file and instantly see the new version in a browser the same way
> > it
> > > > will be represented on the website.
> > > >
> > > > Asciidoc has features where you can include snippets/classes/methods
> of
> > > > your source code in your documentation, they are dynamically linked.
> > This
> > > > means that if the method changes the docs will be updated instantly.
> > > Though
> > > > we would have to test if these features work in our current setup
> this
> > > can
> > > > be a great addition to our developer documentation.
> > > >
> > > > As always this mail is to gather feedback and your opinion on the
> > matter
> > > > before we start changing things.
> > > >
> > > > Cheers,
> > > > Hans
> > > >
> > > > [1] https://github.com/apache/incubator-hop-docs
> > > >
> > >
> >
>

Re: [DISCUSS] Documentation Location

[Hiromu Hota <hi...@gmail.com>]

+1. Mono-repo-> easier to manage.

Thanks,
Hiromu

On Sun, Apr 11, 2021 at 8:52 PM Brandon Jackson <us...@gmail.com> wrote:

> I like this idea too.  +1 from me.
>
> Brandon
>
> On Sun, Apr 11, 2021 at 12:53 PM Matt Casters
> <ma...@neo4j.com.invalid> wrote:
>
> > +1 from me as well Hans.  It's a great idea.  Sometimes I think it's
> better
> > to just do the work in the short term to avoid the accumulated pain over
> > time.
> > I certainly didn't have a lot of fun updating docs in the source code
> > (plugin information) along with their navigation and index pages in the
> > docs and so on.
> > What you propose would solve most of the issues I was having.
> > Cheers,
> > Matt
> >
> > On Sat, Apr 10, 2021 at 6:56 PM Hans Van Akelyen <
> > hans.van.akelyen@gmail.com>
> > wrote:
> >
> > > Hi All,
> > >
> > > When we started this project we started with a separate documentation
> > > repository [1].
> > >
> > > While this seemed a great idea at the time I would like to come back to
> > > this subject. I would like to propose to merge our documentation to our
> > > source code repository.
> > >
> > > There are three main advantages:
> > > - Single source for releases
> > > - Simpler testing
> > > - More advanced asciidoc features
> > >
> > > When creating a release we will automatically have a branch that
> contains
> > > the documentation that is valid for that release, at this point in time
> > > this is a non-issue as we are not yet creating versions of our
> > > documentation and everything is still aligned, but when we move forward
> > > parts of the documentation will become deprecated or linked to a
> specific
> > > version.
> > >
> > > If we single source our documentation we can include a basic version of
> > our
> > > documentation website to our code repository this will make it simpler
> to
> > > see what the end result will look like. It allows you to do changes in
> an
> > > adoc file and instantly see the new version in a browser the same way
> it
> > > will be represented on the website.
> > >
> > > Asciidoc has features where you can include snippets/classes/methods of
> > > your source code in your documentation, they are dynamically linked.
> This
> > > means that if the method changes the docs will be updated instantly.
> > Though
> > > we would have to test if these features work in our current setup this
> > can
> > > be a great addition to our developer documentation.
> > >
> > > As always this mail is to gather feedback and your opinion on the
> matter
> > > before we start changing things.
> > >
> > > Cheers,
> > > Hans
> > >
> > > [1] https://github.com/apache/incubator-hop-docs
> > >
> >
>

Re: [DISCUSS] Documentation Location

[Brandon Jackson <us...@gmail.com>]

I like this idea too.  +1 from me.

Brandon

On Sun, Apr 11, 2021 at 12:53 PM Matt Casters
<ma...@neo4j.com.invalid> wrote:

> +1 from me as well Hans.  It's a great idea.  Sometimes I think it's better
> to just do the work in the short term to avoid the accumulated pain over
> time.
> I certainly didn't have a lot of fun updating docs in the source code
> (plugin information) along with their navigation and index pages in the
> docs and so on.
> What you propose would solve most of the issues I was having.
> Cheers,
> Matt
>
> On Sat, Apr 10, 2021 at 6:56 PM Hans Van Akelyen <
> hans.van.akelyen@gmail.com>
> wrote:
>
> > Hi All,
> >
> > When we started this project we started with a separate documentation
> > repository [1].
> >
> > While this seemed a great idea at the time I would like to come back to
> > this subject. I would like to propose to merge our documentation to our
> > source code repository.
> >
> > There are three main advantages:
> > - Single source for releases
> > - Simpler testing
> > - More advanced asciidoc features
> >
> > When creating a release we will automatically have a branch that contains
> > the documentation that is valid for that release, at this point in time
> > this is a non-issue as we are not yet creating versions of our
> > documentation and everything is still aligned, but when we move forward
> > parts of the documentation will become deprecated or linked to a specific
> > version.
> >
> > If we single source our documentation we can include a basic version of
> our
> > documentation website to our code repository this will make it simpler to
> > see what the end result will look like. It allows you to do changes in an
> > adoc file and instantly see the new version in a browser the same way it
> > will be represented on the website.
> >
> > Asciidoc has features where you can include snippets/classes/methods of
> > your source code in your documentation, they are dynamically linked. This
> > means that if the method changes the docs will be updated instantly.
> Though
> > we would have to test if these features work in our current setup this
> can
> > be a great addition to our developer documentation.
> >
> > As always this mail is to gather feedback and your opinion on the matter
> > before we start changing things.
> >
> > Cheers,
> > Hans
> >
> > [1] https://github.com/apache/incubator-hop-docs
> >
>

Re: [DISCUSS] Documentation Location

[Matt Casters <ma...@neo4j.com.INVALID>]

+1 from me as well Hans.  It's a great idea.  Sometimes I think it's better
to just do the work in the short term to avoid the accumulated pain over
time.
I certainly didn't have a lot of fun updating docs in the source code
(plugin information) along with their navigation and index pages in the
docs and so on.
What you propose would solve most of the issues I was having.
Cheers,
Matt

On Sat, Apr 10, 2021 at 6:56 PM Hans Van Akelyen <ha...@gmail.com>
wrote:

> Hi All,
>
> When we started this project we started with a separate documentation
> repository [1].
>
> While this seemed a great idea at the time I would like to come back to
> this subject. I would like to propose to merge our documentation to our
> source code repository.
>
> There are three main advantages:
> - Single source for releases
> - Simpler testing
> - More advanced asciidoc features
>
> When creating a release we will automatically have a branch that contains
> the documentation that is valid for that release, at this point in time
> this is a non-issue as we are not yet creating versions of our
> documentation and everything is still aligned, but when we move forward
> parts of the documentation will become deprecated or linked to a specific
> version.
>
> If we single source our documentation we can include a basic version of our
> documentation website to our code repository this will make it simpler to
> see what the end result will look like. It allows you to do changes in an
> adoc file and instantly see the new version in a browser the same way it
> will be represented on the website.
>
> Asciidoc has features where you can include snippets/classes/methods of
> your source code in your documentation, they are dynamically linked. This
> means that if the method changes the docs will be updated instantly. Though
> we would have to test if these features work in our current setup this can
> be a great addition to our developer documentation.
>
> As always this mail is to gather feedback and your opinion on the matter
> before we start changing things.
>
> Cheers,
> Hans
>
> [1] https://github.com/apache/incubator-hop-docs
>