You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hop.apache.org by Hans Van Akelyen <ha...@gmail.com> on 2021/02/21 08:46:25 UTC
Documentation
Hi Hoppers,
I would like to restructure the documentation a bit and would love for your
opinion on the matter.
Currently all our transforms and actions are gathered under the plugins
section, this made sense when we started working on the project but from a
user perspective this is confusing.
The suggestion is to make at least 2 large categories to the documentation
being "Pipeline" and "Workflow" we can then move the documentation that is
located under "Hop Gui" or rewrite parts of this documentation and do cross
references when needed.
I think making these 2 large sections and adding the transforms/actions
here will greatly improve readability. We can still use the plugins section
too, we can use it for external plugins or transforms/actions that we will
not be adding to the default release in the future.
Cheers,
Hans
Re: Documentation
Posted by Hans Van Akelyen <ha...@gmail.com>.
Thanks for the feedback!
Another small remark from the chat :
nadment: You should add the VFS concept below variable
I will proceed with moving everything to the new structure, create
placeholders for new content and create tickets so we can follow up.
Cheers,
Hans
On Thu, 11 Mar 2021 at 11:42, Brandon Jackson <us...@gmail.com> wrote:
> I like the new layout. I would like to see the layout support mobile a
> little better. Half the screen gets eaten for a cookies pop up each visit
> and a content bar gets stuck in the top 2/3 of the content when scrolling.
>
>
>
> Sent from my iPhone
>
> > On Mar 11, 2021, at 2:59 AM, Bart Maertens <ba...@know.bi>
> wrote:
> >
> > Agreed, this is a significant improvement!
> >
> > Once these changes have been pushed, I'll see if we can do a better job
> of
> > tracking which documentation pages are visited and which ones may go
> > unnoticed. If we don't measure, we don't know.
> >
> >> On Thu, Mar 11, 2021 at 9:39 AM Matt Casters <matt.casters@neo4j.com
> .invalid>
> >> wrote:
> >>
> >> I really like the new structure. I'm not against leaving place-holders
> as
> >> well to remind us where documentation might be missing.
> >>
> >>
> >> On Wed, Mar 10, 2021 at 9:42 PM Hans Van Akelyen <
> >> hans.van.akelyen@gmail.com>
> >> wrote:
> >>
> >>> Hi All,
> >>>
> >>> I have created a first draft for the new structure for the
> documentation
> >>> and would love some feedback.
> >>> The new Lay out can be found here:
> >>> https://hop.apache.org/manual/New%20Layout/index.html
> >>>
> >>> Please note that only the structure has changed (left hand side), the
> >>> content does not match the structure and some links will not work as
> >>> expected. I would first like to have some feedback and will then
> proceed
> >> in
> >>> changing all the pages.
> >>>
> >>> I have a feeling the new structure is more user oriented and less
> >>> confusing, as a general rule of thumb I kept everything at max 3 levels
> >>> deep (who would dig even further? I know I wouldn't) and sorted them in
> >>> what I hope is a logical order.
> >>>
> >>>
> >>> Cheers,
> >>> Hans
> >>>
> >>> On Mon, 22 Feb 2021 at 10:27, Hans Van Akelyen <
> >> hans.van.akelyen@gmail.com
> >>>>
> >>> wrote:
> >>>
> >>>> I think we should indeed see the user manual as a user oriented and
> >> thus
> >>>> Hop GUI manual, though it can still contain concepts and more textual
> >>>> information needed to grasp all the concepts and components that Hop
> >>>> contains.
> >>>>
> >>>> The more technical information on how to use CLI and configure
> (server)
> >>>> environments should go to the technical documentation. As most users
> >> will
> >>>> not use this on a day to day basis.
> >>>>
> >>>> Cheers,
> >>>> Hans
> >>>>
> >>>> On Mon, Feb 22, 2021 at 9:53 AM Bart Maertens <ba...@know.bi>
> >>>> wrote:
> >>>>
> >>>>> So the discussion is basically: do we include a Hop Gui top section
> or
> >>>>> not?
> >>>>> In that case, the user manual more or less becomes the Hop Gui
> manual.
> >>>>>
> >>>>> While we're at it, we could move the 'Tools' section to the
> >>>>> technical manual, where the Docker documentation currently is.
> >>>>> The technical guide needs some cleanup anyway: getting started is
> >> empty
> >>> so
> >>>>> can be removed, the hop-uit docs can go as well.
> >>>>> The 'logo and icons' is definitely useful, but is a style guide
> rather
> >>>>> than
> >>>>> purely technical documentation.
> >>>>>
> >>>>>
> >>>>> On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <
> >>>>> hans.van.akelyen@gmail.com>
> >>>>> wrote:
> >>>>>
> >>>>>> Hi Bart,
> >>>>>>
> >>>>>> This is why I suggest removing the top level in your structure all
> >>>>>> together...
> >>>>>> 95% of what is written in the user manual is "Hop GUI" as you
> >>> structure
> >>>>>> ends up with 4 levels the users will get lost.
> >>>>>> Most documentation I see in the field tries to keep it at 2 levels
> >>> with
> >>>>> 3
> >>>>>> levels being the exception. Users don't like to dig into sub levels
> >> (I
> >>>>> know
> >>>>>> I don't).
> >>>>>> Imho everything there should be written from a gui perspective.
> >>>>>>
> >>>>>> If you go to what we have in the "pipeline" and "workflow" section
> >>> now,
> >>>>> it
> >>>>>> is just a placeholder for the links under it.
> >>>>>> That's why I added the let's add the general concept there and then
> >> on
> >>>>>> level 2 add all the "editor"/"config"/....
> >>>>>>
> >>>>>> A/B testing might be a path to follow, but then we need to gather
> >> more
> >>>>>> information than we do now and have to start analyzing it. I suggest
> >>>>> this
> >>>>>> is something for the future. I do not think we have what it takes to
> >>> add
> >>>>>> clickstream/reading info from our website at this point in time
> >>>>>>
> >>>>>> Cheers,
> >>>>>> Hans
> >>>>>>
> >>>>>>
> >>>>>> On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <
> >> bart.maertens@know.bi>
> >>>>>> wrote:
> >>>>>>
> >>>>>>> Hop users will spend almost all of their time in Hop Gui, e.g.
> >>> nobody
> >>>>>> will
> >>>>>>> create an action or transform outside of Hop Gui.
> >>>>>>> People will look for documentation where they will use and need
> >> it,
> >>>>> not
> >>>>>>> where it makes most sense from a conceptual or technical point of
> >>>>> view.
> >>>>>>>
> >>>>>>> Since the discussion is mostly around how we structure the left
> >> hand
> >>>>> TOC
> >>>>>>> menu,we could do some A/B testing: refer to workflow, pipeline and
> >>>>> other
> >>>>>>> docs from their own main sections in the ToC *and* from the Hop
> >> Gui
> >>>>>>> section.
> >>>>>>> If we measure which path users follow to get to a documentation
> >>> page
> >>>>> and
> >>>>>>> one turns out to be underused, we can phase it out.
> >>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>> On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
> >>>>>>> hans.van.akelyen@gmail.com> wrote:
> >>>>>>>
> >>>>>>>> I also have a feeling the GUI topic is too broad and would
> >> contain
> >>>>>>>> everything making it useless...
> >>>>>>>> This is what happened now with the plugins section.
> >>>>>>>> I think we can also remove the GUI heading and just talk about
> >>>>> concepts
> >>>>>>> and
> >>>>>>>> as a subtopic how they are handled in the GUI.
> >>>>>>>>
> >>>>>>>> - > Workflow (general concept)
> >>>>>>>> - - > Creating a workflow (GUI explanation)
> >>>>>>>> - - > Actions
> >>>>>>>> - - - > Action 1
> >>>>>>>> - - - > Action 2
> >>>>>>>> ....
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>> On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
> >>>>>>>> <ma...@neo4j.com.invalid> wrote:
> >>>>>>>>
> >>>>>>>>> I'm not sure I like the idea of putting everything and the
> >>> kitchen
> >>>>>> sink
> >>>>>>>>> under "Hop GUI". Maybe we can flatten the tree a bit?
> >>>>>>>>> Perhaps we can have a number of top level entries like
> >>> Workflows,
> >>>>>>>>> Pipelines, Metadata, Tools, ...?
> >>>>>>>>> We can put the password encryption plugin under the Hop Encr
> >>> tool
> >>>>> or
> >>>>>>>> under
> >>>>>>>>> a more generic "Security" heading. It's a non-trivial concern
> >>>>> after
> >>>>>>> all.
> >>>>>>>>>
> >>>>>>>>> Cheers,
> >>>>>>>>> Matt
> >>>>>>>>>
> >>>>>>>>> On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <
> >>>>> bart.maertens@know.bi
> >>>>>>>
> >>>>>>>>> wrote:
> >>>>>>>>>
> >>>>>>>>>> Hi Hans, All,
> >>>>>>>>>>
> >>>>>>>>>> I agree moving the plugin documentation out of the plugins
> >>>>> category
> >>>>>>> is
> >>>>>>>> a
> >>>>>>>>>> necessity.
> >>>>>>>>>> Our initial structure was inspired by the Hop architecture,
> >>>>> which
> >>>>>>> imho
> >>>>>>>>> is a
> >>>>>>>>>> way too technical perspective.
> >>>>>>>>>> The documentation structure should follow how people use Hop
> >>> and
> >>>>>>> where
> >>>>>>>>> they
> >>>>>>>>>> would look for information.
> >>>>>>>>>>
> >>>>>>>>>> People will interact with transforms, actions, project &
> >>>>> database
> >>>>>>>> config
> >>>>>>>>>> etc almost exclusively from Hop Gui.
> >>>>>>>>>> Therefore, my suggestion would be to use the 2 main
> >> 'Workflow'
> >>>>> and
> >>>>>>>>>> 'Pipeline' sections you mentioned, but keep them in the Hop
> >>> Gui
> >>>>>>>> section.
> >>>>>>>>>> Something like:
> >>>>>>>>>> - > Hop Gui
> >>>>>>>>>> - - > Workflows
> >>>>>>>>>> - - -> Workflow Editor
> >>>>>>>>>> - - - > Workflow Run Configurations
> >>>>>>>>>> - - - > Actions
> >>>>>>>>>> - - - > ....
> >>>>>>>>>> - - > Pipelines
> >>>>>>>>>> - - - > Pipeline Editor
> >>>>>>>>>> - - - > Pipeline Run Configurations
> >>>>>>>>>> - - - > Transforms
> >>>>>>>>>> - - - > ....
> >>>>>>>>>> - - > Testing
> >>>>>>>>>> - - > Projects & Environments
> >>>>>>>>>> - - > Metadata
> >>>>>>>>>> - - - > Databases
> >>>>>>>>>> - - > ....
> >>>>>>>>>>
> >>>>>>>>>> For the more configuration/administration oriented tasks, we
> >>>>> could
> >>>>>>> add
> >>>>>>>> a
> >>>>>>>>>> Tools/Administration/Configuration section, something like:
> >>>>>>>>>> - > Tools (or Administration?)
> >>>>>>>>>> - - > Hop Conf
> >>>>>>>>>> - - > Hop Server
> >>>>>>>>>> - - > Hop Run
> >>>>>>>>>>
> >>>>>>>>>> I'm not sure where e.g. the password plugins would fit in,
> >>> since
> >>>>>>>> they're
> >>>>>>>>>> not directly development or configuration related. We could
> >>> keep
> >>>>>>> those
> >>>>>>>> in
> >>>>>>>>>> the current 'Plugins' section.
> >>>>>>>>>> - > Plugins
> >>>>>>>>>> - - > Password Plugins
> >>>>>>>>>>
> >>>>>>>>>> Regards,
> >>>>>>>>>> Bart
> >>>>>>>>>>
> >>>>>>>>>> On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> >>>>>>>>>> hans.van.akelyen@gmail.com>
> >>>>>>>>>> wrote:
> >>>>>>>>>>
> >>>>>>>>>>> Hi Hoppers,
> >>>>>>>>>>>
> >>>>>>>>>>> I would like to restructure the documentation a bit and
> >>> would
> >>>>>> love
> >>>>>>>> for
> >>>>>>>>>> your
> >>>>>>>>>>> opinion on the matter.
> >>>>>>>>>>> Currently all our transforms and actions are gathered
> >> under
> >>>>> the
> >>>>>>>> plugins
> >>>>>>>>>>> section, this made sense when we started working on the
> >>>>> project
> >>>>>> but
> >>>>>>>>> from
> >>>>>>>>>> a
> >>>>>>>>>>> user perspective this is confusing.
> >>>>>>>>>>>
> >>>>>>>>>>> The suggestion is to make at least 2 large categories to
> >> the
> >>>>>>>>>> documentation
> >>>>>>>>>>> being "Pipeline" and "Workflow" we can then move the
> >>>>>> documentation
> >>>>>>>> that
> >>>>>>>>>> is
> >>>>>>>>>>> located under "Hop Gui" or rewrite parts of this
> >>> documentation
> >>>>>> and
> >>>>>>> do
> >>>>>>>>>> cross
> >>>>>>>>>>> references when needed.
> >>>>>>>>>>>
> >>>>>>>>>>> I think making these 2 large sections and adding the
> >>>>>>>> transforms/actions
> >>>>>>>>>>> here will greatly improve readability. We can still use
> >> the
> >>>>>> plugins
> >>>>>>>>>> section
> >>>>>>>>>>> too, we can use it for external plugins or
> >>> transforms/actions
> >>>>>> that
> >>>>>>> we
> >>>>>>>>>> will
> >>>>>>>>>>> not be adding to the default release in the future.
> >>>>>>>>>>>
> >>>>>>>>>>> Cheers,
> >>>>>>>>>>> Hans
> >>>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>> --
> >>>>>>>>> Neo4j Chief Solutions Architect
> >>>>>>>>> *✉ *matt.casters@neo4j.com
> >>>>>>>>> ☎ +32486972937
> >>>>>>>>>
> >>>>>>>>
> >>>>>>>
> >>>>>>
> >>>>>
> >>>>
> >>>
> >>
> >>
> >> --
> >> Neo4j Chief Solutions Architect
> >> *✉ *matt.casters@neo4j.com
> >> ☎ +32486972937
> >>
>
Re: Documentation
Posted by Bart Maertens <ba...@know.bi>.
One more change we can make to improve the user experience for the
documentation and the entire website is to make the dropdown menu headers
(docs and community) clickable.
This would not only give us high level and easy to remember urls (
https://hop.apache.org/docs, https://hop.apache.org/community).
We can use the landing pages behind those urls to provide some more
guidance.
For the docs, this could be a quick one line explanation of what to expect
in the user/tech/dev/... docs, offer pdf versions copies for download, link
to different doc versions etc.
Regards,
Bart
On Fri, Mar 12, 2021 at 6:23 PM Bart Maertens <ba...@know.bi> wrote:
> Hi Brandon,
>
> HOP-2603 has been implemented to improve the website on mobile.
> There may be more tweaks and tuning we can do to improve the mobile
> experience, let us know if you have any suggestions.
>
> Regards,
> Bart
>
>
> On Thu, Mar 11, 2021 at 11:42 AM Brandon Jackson <us...@gmail.com>
> wrote:
>
>> I like the new layout. I would like to see the layout support mobile a
>> little better. Half the screen gets eaten for a cookies pop up each visit
>> and a content bar gets stuck in the top 2/3 of the content when scrolling.
>>
>>
>>
>> Sent from my iPhone
>>
>> > On Mar 11, 2021, at 2:59 AM, Bart Maertens <ba...@know.bi>
>> wrote:
>> >
>> > Agreed, this is a significant improvement!
>> >
>> > Once these changes have been pushed, I'll see if we can do a better job
>> of
>> > tracking which documentation pages are visited and which ones may go
>> > unnoticed. If we don't measure, we don't know.
>> >
>> >> On Thu, Mar 11, 2021 at 9:39 AM Matt Casters <matt.casters@neo4j.com
>> .invalid>
>> >> wrote:
>> >>
>> >> I really like the new structure. I'm not against leaving
>> place-holders as
>> >> well to remind us where documentation might be missing.
>> >>
>> >>
>> >> On Wed, Mar 10, 2021 at 9:42 PM Hans Van Akelyen <
>> >> hans.van.akelyen@gmail.com>
>> >> wrote:
>> >>
>> >>> Hi All,
>> >>>
>> >>> I have created a first draft for the new structure for the
>> documentation
>> >>> and would love some feedback.
>> >>> The new Lay out can be found here:
>> >>> https://hop.apache.org/manual/New%20Layout/index.html
>> >>>
>> >>> Please note that only the structure has changed (left hand side), the
>> >>> content does not match the structure and some links will not work as
>> >>> expected. I would first like to have some feedback and will then
>> proceed
>> >> in
>> >>> changing all the pages.
>> >>>
>> >>> I have a feeling the new structure is more user oriented and less
>> >>> confusing, as a general rule of thumb I kept everything at max 3
>> levels
>> >>> deep (who would dig even further? I know I wouldn't) and sorted them
>> in
>> >>> what I hope is a logical order.
>> >>>
>> >>>
>> >>> Cheers,
>> >>> Hans
>> >>>
>> >>> On Mon, 22 Feb 2021 at 10:27, Hans Van Akelyen <
>> >> hans.van.akelyen@gmail.com
>> >>>>
>> >>> wrote:
>> >>>
>> >>>> I think we should indeed see the user manual as a user oriented and
>> >> thus
>> >>>> Hop GUI manual, though it can still contain concepts and more textual
>> >>>> information needed to grasp all the concepts and components that Hop
>> >>>> contains.
>> >>>>
>> >>>> The more technical information on how to use CLI and configure
>> (server)
>> >>>> environments should go to the technical documentation. As most users
>> >> will
>> >>>> not use this on a day to day basis.
>> >>>>
>> >>>> Cheers,
>> >>>> Hans
>> >>>>
>> >>>> On Mon, Feb 22, 2021 at 9:53 AM Bart Maertens <bart.maertens@know.bi
>> >
>> >>>> wrote:
>> >>>>
>> >>>>> So the discussion is basically: do we include a Hop Gui top section
>> or
>> >>>>> not?
>> >>>>> In that case, the user manual more or less becomes the Hop Gui
>> manual.
>> >>>>>
>> >>>>> While we're at it, we could move the 'Tools' section to the
>> >>>>> technical manual, where the Docker documentation currently is.
>> >>>>> The technical guide needs some cleanup anyway: getting started is
>> >> empty
>> >>> so
>> >>>>> can be removed, the hop-uit docs can go as well.
>> >>>>> The 'logo and icons' is definitely useful, but is a style guide
>> rather
>> >>>>> than
>> >>>>> purely technical documentation.
>> >>>>>
>> >>>>>
>> >>>>> On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <
>> >>>>> hans.van.akelyen@gmail.com>
>> >>>>> wrote:
>> >>>>>
>> >>>>>> Hi Bart,
>> >>>>>>
>> >>>>>> This is why I suggest removing the top level in your structure all
>> >>>>>> together...
>> >>>>>> 95% of what is written in the user manual is "Hop GUI" as you
>> >>> structure
>> >>>>>> ends up with 4 levels the users will get lost.
>> >>>>>> Most documentation I see in the field tries to keep it at 2 levels
>> >>> with
>> >>>>> 3
>> >>>>>> levels being the exception. Users don't like to dig into sub levels
>> >> (I
>> >>>>> know
>> >>>>>> I don't).
>> >>>>>> Imho everything there should be written from a gui perspective.
>> >>>>>>
>> >>>>>> If you go to what we have in the "pipeline" and "workflow" section
>> >>> now,
>> >>>>> it
>> >>>>>> is just a placeholder for the links under it.
>> >>>>>> That's why I added the let's add the general concept there and then
>> >> on
>> >>>>>> level 2 add all the "editor"/"config"/....
>> >>>>>>
>> >>>>>> A/B testing might be a path to follow, but then we need to gather
>> >> more
>> >>>>>> information than we do now and have to start analyzing it. I
>> suggest
>> >>>>> this
>> >>>>>> is something for the future. I do not think we have what it takes
>> to
>> >>> add
>> >>>>>> clickstream/reading info from our website at this point in time
>> >>>>>>
>> >>>>>> Cheers,
>> >>>>>> Hans
>> >>>>>>
>> >>>>>>
>> >>>>>> On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <
>> >> bart.maertens@know.bi>
>> >>>>>> wrote:
>> >>>>>>
>> >>>>>>> Hop users will spend almost all of their time in Hop Gui, e.g.
>> >>> nobody
>> >>>>>> will
>> >>>>>>> create an action or transform outside of Hop Gui.
>> >>>>>>> People will look for documentation where they will use and need
>> >> it,
>> >>>>> not
>> >>>>>>> where it makes most sense from a conceptual or technical point of
>> >>>>> view.
>> >>>>>>>
>> >>>>>>> Since the discussion is mostly around how we structure the left
>> >> hand
>> >>>>> TOC
>> >>>>>>> menu,we could do some A/B testing: refer to workflow, pipeline and
>> >>>>> other
>> >>>>>>> docs from their own main sections in the ToC *and* from the Hop
>> >> Gui
>> >>>>>>> section.
>> >>>>>>> If we measure which path users follow to get to a documentation
>> >>> page
>> >>>>> and
>> >>>>>>> one turns out to be underused, we can phase it out.
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>> On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
>> >>>>>>> hans.van.akelyen@gmail.com> wrote:
>> >>>>>>>
>> >>>>>>>> I also have a feeling the GUI topic is too broad and would
>> >> contain
>> >>>>>>>> everything making it useless...
>> >>>>>>>> This is what happened now with the plugins section.
>> >>>>>>>> I think we can also remove the GUI heading and just talk about
>> >>>>> concepts
>> >>>>>>> and
>> >>>>>>>> as a subtopic how they are handled in the GUI.
>> >>>>>>>>
>> >>>>>>>> - > Workflow (general concept)
>> >>>>>>>> - - > Creating a workflow (GUI explanation)
>> >>>>>>>> - - > Actions
>> >>>>>>>> - - - > Action 1
>> >>>>>>>> - - - > Action 2
>> >>>>>>>> ....
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>> On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
>> >>>>>>>> <ma...@neo4j.com.invalid> wrote:
>> >>>>>>>>
>> >>>>>>>>> I'm not sure I like the idea of putting everything and the
>> >>> kitchen
>> >>>>>> sink
>> >>>>>>>>> under "Hop GUI". Maybe we can flatten the tree a bit?
>> >>>>>>>>> Perhaps we can have a number of top level entries like
>> >>> Workflows,
>> >>>>>>>>> Pipelines, Metadata, Tools, ...?
>> >>>>>>>>> We can put the password encryption plugin under the Hop Encr
>> >>> tool
>> >>>>> or
>> >>>>>>>> under
>> >>>>>>>>> a more generic "Security" heading. It's a non-trivial concern
>> >>>>> after
>> >>>>>>> all.
>> >>>>>>>>>
>> >>>>>>>>> Cheers,
>> >>>>>>>>> Matt
>> >>>>>>>>>
>> >>>>>>>>> On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <
>> >>>>> bart.maertens@know.bi
>> >>>>>>>
>> >>>>>>>>> wrote:
>> >>>>>>>>>
>> >>>>>>>>>> Hi Hans, All,
>> >>>>>>>>>>
>> >>>>>>>>>> I agree moving the plugin documentation out of the plugins
>> >>>>> category
>> >>>>>>> is
>> >>>>>>>> a
>> >>>>>>>>>> necessity.
>> >>>>>>>>>> Our initial structure was inspired by the Hop architecture,
>> >>>>> which
>> >>>>>>> imho
>> >>>>>>>>> is a
>> >>>>>>>>>> way too technical perspective.
>> >>>>>>>>>> The documentation structure should follow how people use Hop
>> >>> and
>> >>>>>>> where
>> >>>>>>>>> they
>> >>>>>>>>>> would look for information.
>> >>>>>>>>>>
>> >>>>>>>>>> People will interact with transforms, actions, project &
>> >>>>> database
>> >>>>>>>> config
>> >>>>>>>>>> etc almost exclusively from Hop Gui.
>> >>>>>>>>>> Therefore, my suggestion would be to use the 2 main
>> >> 'Workflow'
>> >>>>> and
>> >>>>>>>>>> 'Pipeline' sections you mentioned, but keep them in the Hop
>> >>> Gui
>> >>>>>>>> section.
>> >>>>>>>>>> Something like:
>> >>>>>>>>>> - > Hop Gui
>> >>>>>>>>>> - - > Workflows
>> >>>>>>>>>> - - -> Workflow Editor
>> >>>>>>>>>> - - - > Workflow Run Configurations
>> >>>>>>>>>> - - - > Actions
>> >>>>>>>>>> - - - > ....
>> >>>>>>>>>> - - > Pipelines
>> >>>>>>>>>> - - - > Pipeline Editor
>> >>>>>>>>>> - - - > Pipeline Run Configurations
>> >>>>>>>>>> - - - > Transforms
>> >>>>>>>>>> - - - > ....
>> >>>>>>>>>> - - > Testing
>> >>>>>>>>>> - - > Projects & Environments
>> >>>>>>>>>> - - > Metadata
>> >>>>>>>>>> - - - > Databases
>> >>>>>>>>>> - - > ....
>> >>>>>>>>>>
>> >>>>>>>>>> For the more configuration/administration oriented tasks, we
>> >>>>> could
>> >>>>>>> add
>> >>>>>>>> a
>> >>>>>>>>>> Tools/Administration/Configuration section, something like:
>> >>>>>>>>>> - > Tools (or Administration?)
>> >>>>>>>>>> - - > Hop Conf
>> >>>>>>>>>> - - > Hop Server
>> >>>>>>>>>> - - > Hop Run
>> >>>>>>>>>>
>> >>>>>>>>>> I'm not sure where e.g. the password plugins would fit in,
>> >>> since
>> >>>>>>>> they're
>> >>>>>>>>>> not directly development or configuration related. We could
>> >>> keep
>> >>>>>>> those
>> >>>>>>>> in
>> >>>>>>>>>> the current 'Plugins' section.
>> >>>>>>>>>> - > Plugins
>> >>>>>>>>>> - - > Password Plugins
>> >>>>>>>>>>
>> >>>>>>>>>> Regards,
>> >>>>>>>>>> Bart
>> >>>>>>>>>>
>> >>>>>>>>>> On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
>> >>>>>>>>>> hans.van.akelyen@gmail.com>
>> >>>>>>>>>> wrote:
>> >>>>>>>>>>
>> >>>>>>>>>>> Hi Hoppers,
>> >>>>>>>>>>>
>> >>>>>>>>>>> I would like to restructure the documentation a bit and
>> >>> would
>> >>>>>> love
>> >>>>>>>> for
>> >>>>>>>>>> your
>> >>>>>>>>>>> opinion on the matter.
>> >>>>>>>>>>> Currently all our transforms and actions are gathered
>> >> under
>> >>>>> the
>> >>>>>>>> plugins
>> >>>>>>>>>>> section, this made sense when we started working on the
>> >>>>> project
>> >>>>>> but
>> >>>>>>>>> from
>> >>>>>>>>>> a
>> >>>>>>>>>>> user perspective this is confusing.
>> >>>>>>>>>>>
>> >>>>>>>>>>> The suggestion is to make at least 2 large categories to
>> >> the
>> >>>>>>>>>> documentation
>> >>>>>>>>>>> being "Pipeline" and "Workflow" we can then move the
>> >>>>>> documentation
>> >>>>>>>> that
>> >>>>>>>>>> is
>> >>>>>>>>>>> located under "Hop Gui" or rewrite parts of this
>> >>> documentation
>> >>>>>> and
>> >>>>>>> do
>> >>>>>>>>>> cross
>> >>>>>>>>>>> references when needed.
>> >>>>>>>>>>>
>> >>>>>>>>>>> I think making these 2 large sections and adding the
>> >>>>>>>> transforms/actions
>> >>>>>>>>>>> here will greatly improve readability. We can still use
>> >> the
>> >>>>>> plugins
>> >>>>>>>>>> section
>> >>>>>>>>>>> too, we can use it for external plugins or
>> >>> transforms/actions
>> >>>>>> that
>> >>>>>>> we
>> >>>>>>>>>> will
>> >>>>>>>>>>> not be adding to the default release in the future.
>> >>>>>>>>>>>
>> >>>>>>>>>>> Cheers,
>> >>>>>>>>>>> Hans
>> >>>>>>>>>>>
>> >>>>>>>>>>
>> >>>>>>>>>
>> >>>>>>>>>
>> >>>>>>>>> --
>> >>>>>>>>> Neo4j Chief Solutions Architect
>> >>>>>>>>> *✉ *matt.casters@neo4j.com
>> >>>>>>>>> ☎ +32486972937
>> >>>>>>>>>
>> >>>>>>>>
>> >>>>>>>
>> >>>>>>
>> >>>>>
>> >>>>
>> >>>
>> >>
>> >>
>> >> --
>> >> Neo4j Chief Solutions Architect
>> >> *✉ *matt.casters@neo4j.com
>> >> ☎ +32486972937
>> >>
>>
>
Re: Documentation
Posted by Bart Maertens <ba...@know.bi>.
Hi Brandon,
HOP-2603 has been implemented to improve the website on mobile.
There may be more tweaks and tuning we can do to improve the mobile
experience, let us know if you have any suggestions.
Regards,
Bart
On Thu, Mar 11, 2021 at 11:42 AM Brandon Jackson <us...@gmail.com>
wrote:
> I like the new layout. I would like to see the layout support mobile a
> little better. Half the screen gets eaten for a cookies pop up each visit
> and a content bar gets stuck in the top 2/3 of the content when scrolling.
>
>
>
> Sent from my iPhone
>
> > On Mar 11, 2021, at 2:59 AM, Bart Maertens <ba...@know.bi>
> wrote:
> >
> > Agreed, this is a significant improvement!
> >
> > Once these changes have been pushed, I'll see if we can do a better job
> of
> > tracking which documentation pages are visited and which ones may go
> > unnoticed. If we don't measure, we don't know.
> >
> >> On Thu, Mar 11, 2021 at 9:39 AM Matt Casters <matt.casters@neo4j.com
> .invalid>
> >> wrote:
> >>
> >> I really like the new structure. I'm not against leaving place-holders
> as
> >> well to remind us where documentation might be missing.
> >>
> >>
> >> On Wed, Mar 10, 2021 at 9:42 PM Hans Van Akelyen <
> >> hans.van.akelyen@gmail.com>
> >> wrote:
> >>
> >>> Hi All,
> >>>
> >>> I have created a first draft for the new structure for the
> documentation
> >>> and would love some feedback.
> >>> The new Lay out can be found here:
> >>> https://hop.apache.org/manual/New%20Layout/index.html
> >>>
> >>> Please note that only the structure has changed (left hand side), the
> >>> content does not match the structure and some links will not work as
> >>> expected. I would first like to have some feedback and will then
> proceed
> >> in
> >>> changing all the pages.
> >>>
> >>> I have a feeling the new structure is more user oriented and less
> >>> confusing, as a general rule of thumb I kept everything at max 3 levels
> >>> deep (who would dig even further? I know I wouldn't) and sorted them in
> >>> what I hope is a logical order.
> >>>
> >>>
> >>> Cheers,
> >>> Hans
> >>>
> >>> On Mon, 22 Feb 2021 at 10:27, Hans Van Akelyen <
> >> hans.van.akelyen@gmail.com
> >>>>
> >>> wrote:
> >>>
> >>>> I think we should indeed see the user manual as a user oriented and
> >> thus
> >>>> Hop GUI manual, though it can still contain concepts and more textual
> >>>> information needed to grasp all the concepts and components that Hop
> >>>> contains.
> >>>>
> >>>> The more technical information on how to use CLI and configure
> (server)
> >>>> environments should go to the technical documentation. As most users
> >> will
> >>>> not use this on a day to day basis.
> >>>>
> >>>> Cheers,
> >>>> Hans
> >>>>
> >>>> On Mon, Feb 22, 2021 at 9:53 AM Bart Maertens <ba...@know.bi>
> >>>> wrote:
> >>>>
> >>>>> So the discussion is basically: do we include a Hop Gui top section
> or
> >>>>> not?
> >>>>> In that case, the user manual more or less becomes the Hop Gui
> manual.
> >>>>>
> >>>>> While we're at it, we could move the 'Tools' section to the
> >>>>> technical manual, where the Docker documentation currently is.
> >>>>> The technical guide needs some cleanup anyway: getting started is
> >> empty
> >>> so
> >>>>> can be removed, the hop-uit docs can go as well.
> >>>>> The 'logo and icons' is definitely useful, but is a style guide
> rather
> >>>>> than
> >>>>> purely technical documentation.
> >>>>>
> >>>>>
> >>>>> On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <
> >>>>> hans.van.akelyen@gmail.com>
> >>>>> wrote:
> >>>>>
> >>>>>> Hi Bart,
> >>>>>>
> >>>>>> This is why I suggest removing the top level in your structure all
> >>>>>> together...
> >>>>>> 95% of what is written in the user manual is "Hop GUI" as you
> >>> structure
> >>>>>> ends up with 4 levels the users will get lost.
> >>>>>> Most documentation I see in the field tries to keep it at 2 levels
> >>> with
> >>>>> 3
> >>>>>> levels being the exception. Users don't like to dig into sub levels
> >> (I
> >>>>> know
> >>>>>> I don't).
> >>>>>> Imho everything there should be written from a gui perspective.
> >>>>>>
> >>>>>> If you go to what we have in the "pipeline" and "workflow" section
> >>> now,
> >>>>> it
> >>>>>> is just a placeholder for the links under it.
> >>>>>> That's why I added the let's add the general concept there and then
> >> on
> >>>>>> level 2 add all the "editor"/"config"/....
> >>>>>>
> >>>>>> A/B testing might be a path to follow, but then we need to gather
> >> more
> >>>>>> information than we do now and have to start analyzing it. I suggest
> >>>>> this
> >>>>>> is something for the future. I do not think we have what it takes to
> >>> add
> >>>>>> clickstream/reading info from our website at this point in time
> >>>>>>
> >>>>>> Cheers,
> >>>>>> Hans
> >>>>>>
> >>>>>>
> >>>>>> On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <
> >> bart.maertens@know.bi>
> >>>>>> wrote:
> >>>>>>
> >>>>>>> Hop users will spend almost all of their time in Hop Gui, e.g.
> >>> nobody
> >>>>>> will
> >>>>>>> create an action or transform outside of Hop Gui.
> >>>>>>> People will look for documentation where they will use and need
> >> it,
> >>>>> not
> >>>>>>> where it makes most sense from a conceptual or technical point of
> >>>>> view.
> >>>>>>>
> >>>>>>> Since the discussion is mostly around how we structure the left
> >> hand
> >>>>> TOC
> >>>>>>> menu,we could do some A/B testing: refer to workflow, pipeline and
> >>>>> other
> >>>>>>> docs from their own main sections in the ToC *and* from the Hop
> >> Gui
> >>>>>>> section.
> >>>>>>> If we measure which path users follow to get to a documentation
> >>> page
> >>>>> and
> >>>>>>> one turns out to be underused, we can phase it out.
> >>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>> On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
> >>>>>>> hans.van.akelyen@gmail.com> wrote:
> >>>>>>>
> >>>>>>>> I also have a feeling the GUI topic is too broad and would
> >> contain
> >>>>>>>> everything making it useless...
> >>>>>>>> This is what happened now with the plugins section.
> >>>>>>>> I think we can also remove the GUI heading and just talk about
> >>>>> concepts
> >>>>>>> and
> >>>>>>>> as a subtopic how they are handled in the GUI.
> >>>>>>>>
> >>>>>>>> - > Workflow (general concept)
> >>>>>>>> - - > Creating a workflow (GUI explanation)
> >>>>>>>> - - > Actions
> >>>>>>>> - - - > Action 1
> >>>>>>>> - - - > Action 2
> >>>>>>>> ....
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>> On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
> >>>>>>>> <ma...@neo4j.com.invalid> wrote:
> >>>>>>>>
> >>>>>>>>> I'm not sure I like the idea of putting everything and the
> >>> kitchen
> >>>>>> sink
> >>>>>>>>> under "Hop GUI". Maybe we can flatten the tree a bit?
> >>>>>>>>> Perhaps we can have a number of top level entries like
> >>> Workflows,
> >>>>>>>>> Pipelines, Metadata, Tools, ...?
> >>>>>>>>> We can put the password encryption plugin under the Hop Encr
> >>> tool
> >>>>> or
> >>>>>>>> under
> >>>>>>>>> a more generic "Security" heading. It's a non-trivial concern
> >>>>> after
> >>>>>>> all.
> >>>>>>>>>
> >>>>>>>>> Cheers,
> >>>>>>>>> Matt
> >>>>>>>>>
> >>>>>>>>> On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <
> >>>>> bart.maertens@know.bi
> >>>>>>>
> >>>>>>>>> wrote:
> >>>>>>>>>
> >>>>>>>>>> Hi Hans, All,
> >>>>>>>>>>
> >>>>>>>>>> I agree moving the plugin documentation out of the plugins
> >>>>> category
> >>>>>>> is
> >>>>>>>> a
> >>>>>>>>>> necessity.
> >>>>>>>>>> Our initial structure was inspired by the Hop architecture,
> >>>>> which
> >>>>>>> imho
> >>>>>>>>> is a
> >>>>>>>>>> way too technical perspective.
> >>>>>>>>>> The documentation structure should follow how people use Hop
> >>> and
> >>>>>>> where
> >>>>>>>>> they
> >>>>>>>>>> would look for information.
> >>>>>>>>>>
> >>>>>>>>>> People will interact with transforms, actions, project &
> >>>>> database
> >>>>>>>> config
> >>>>>>>>>> etc almost exclusively from Hop Gui.
> >>>>>>>>>> Therefore, my suggestion would be to use the 2 main
> >> 'Workflow'
> >>>>> and
> >>>>>>>>>> 'Pipeline' sections you mentioned, but keep them in the Hop
> >>> Gui
> >>>>>>>> section.
> >>>>>>>>>> Something like:
> >>>>>>>>>> - > Hop Gui
> >>>>>>>>>> - - > Workflows
> >>>>>>>>>> - - -> Workflow Editor
> >>>>>>>>>> - - - > Workflow Run Configurations
> >>>>>>>>>> - - - > Actions
> >>>>>>>>>> - - - > ....
> >>>>>>>>>> - - > Pipelines
> >>>>>>>>>> - - - > Pipeline Editor
> >>>>>>>>>> - - - > Pipeline Run Configurations
> >>>>>>>>>> - - - > Transforms
> >>>>>>>>>> - - - > ....
> >>>>>>>>>> - - > Testing
> >>>>>>>>>> - - > Projects & Environments
> >>>>>>>>>> - - > Metadata
> >>>>>>>>>> - - - > Databases
> >>>>>>>>>> - - > ....
> >>>>>>>>>>
> >>>>>>>>>> For the more configuration/administration oriented tasks, we
> >>>>> could
> >>>>>>> add
> >>>>>>>> a
> >>>>>>>>>> Tools/Administration/Configuration section, something like:
> >>>>>>>>>> - > Tools (or Administration?)
> >>>>>>>>>> - - > Hop Conf
> >>>>>>>>>> - - > Hop Server
> >>>>>>>>>> - - > Hop Run
> >>>>>>>>>>
> >>>>>>>>>> I'm not sure where e.g. the password plugins would fit in,
> >>> since
> >>>>>>>> they're
> >>>>>>>>>> not directly development or configuration related. We could
> >>> keep
> >>>>>>> those
> >>>>>>>> in
> >>>>>>>>>> the current 'Plugins' section.
> >>>>>>>>>> - > Plugins
> >>>>>>>>>> - - > Password Plugins
> >>>>>>>>>>
> >>>>>>>>>> Regards,
> >>>>>>>>>> Bart
> >>>>>>>>>>
> >>>>>>>>>> On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> >>>>>>>>>> hans.van.akelyen@gmail.com>
> >>>>>>>>>> wrote:
> >>>>>>>>>>
> >>>>>>>>>>> Hi Hoppers,
> >>>>>>>>>>>
> >>>>>>>>>>> I would like to restructure the documentation a bit and
> >>> would
> >>>>>> love
> >>>>>>>> for
> >>>>>>>>>> your
> >>>>>>>>>>> opinion on the matter.
> >>>>>>>>>>> Currently all our transforms and actions are gathered
> >> under
> >>>>> the
> >>>>>>>> plugins
> >>>>>>>>>>> section, this made sense when we started working on the
> >>>>> project
> >>>>>> but
> >>>>>>>>> from
> >>>>>>>>>> a
> >>>>>>>>>>> user perspective this is confusing.
> >>>>>>>>>>>
> >>>>>>>>>>> The suggestion is to make at least 2 large categories to
> >> the
> >>>>>>>>>> documentation
> >>>>>>>>>>> being "Pipeline" and "Workflow" we can then move the
> >>>>>> documentation
> >>>>>>>> that
> >>>>>>>>>> is
> >>>>>>>>>>> located under "Hop Gui" or rewrite parts of this
> >>> documentation
> >>>>>> and
> >>>>>>> do
> >>>>>>>>>> cross
> >>>>>>>>>>> references when needed.
> >>>>>>>>>>>
> >>>>>>>>>>> I think making these 2 large sections and adding the
> >>>>>>>> transforms/actions
> >>>>>>>>>>> here will greatly improve readability. We can still use
> >> the
> >>>>>> plugins
> >>>>>>>>>> section
> >>>>>>>>>>> too, we can use it for external plugins or
> >>> transforms/actions
> >>>>>> that
> >>>>>>> we
> >>>>>>>>>> will
> >>>>>>>>>>> not be adding to the default release in the future.
> >>>>>>>>>>>
> >>>>>>>>>>> Cheers,
> >>>>>>>>>>> Hans
> >>>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>> --
> >>>>>>>>> Neo4j Chief Solutions Architect
> >>>>>>>>> *✉ *matt.casters@neo4j.com
> >>>>>>>>> ☎ +32486972937
> >>>>>>>>>
> >>>>>>>>
> >>>>>>>
> >>>>>>
> >>>>>
> >>>>
> >>>
> >>
> >>
> >> --
> >> Neo4j Chief Solutions Architect
> >> *✉ *matt.casters@neo4j.com
> >> ☎ +32486972937
> >>
>
Re: Documentation
Posted by Brandon Jackson <us...@gmail.com>.
I like the new layout. I would like to see the layout support mobile a little better. Half the screen gets eaten for a cookies pop up each visit and a content bar gets stuck in the top 2/3 of the content when scrolling.
Re: Documentation
Posted by Bart Maertens <ba...@know.bi>.
Agreed, this is a significant improvement!
Once these changes have been pushed, I'll see if we can do a better job of
tracking which documentation pages are visited and which ones may go
unnoticed. If we don't measure, we don't know.
On Thu, Mar 11, 2021 at 9:39 AM Matt Casters <ma...@neo4j.com.invalid>
wrote:
> I really like the new structure. I'm not against leaving place-holders as
> well to remind us where documentation might be missing.
>
>
> On Wed, Mar 10, 2021 at 9:42 PM Hans Van Akelyen <
> hans.van.akelyen@gmail.com>
> wrote:
>
> > Hi All,
> >
> > I have created a first draft for the new structure for the documentation
> > and would love some feedback.
> > The new Lay out can be found here:
> > https://hop.apache.org/manual/New%20Layout/index.html
> >
> > Please note that only the structure has changed (left hand side), the
> > content does not match the structure and some links will not work as
> > expected. I would first like to have some feedback and will then proceed
> in
> > changing all the pages.
> >
> > I have a feeling the new structure is more user oriented and less
> > confusing, as a general rule of thumb I kept everything at max 3 levels
> > deep (who would dig even further? I know I wouldn't) and sorted them in
> > what I hope is a logical order.
> >
> >
> > Cheers,
> > Hans
> >
> > On Mon, 22 Feb 2021 at 10:27, Hans Van Akelyen <
> hans.van.akelyen@gmail.com
> > >
> > wrote:
> >
> > > I think we should indeed see the user manual as a user oriented and
> thus
> > > Hop GUI manual, though it can still contain concepts and more textual
> > > information needed to grasp all the concepts and components that Hop
> > > contains.
> > >
> > > The more technical information on how to use CLI and configure (server)
> > > environments should go to the technical documentation. As most users
> will
> > > not use this on a day to day basis.
> > >
> > > Cheers,
> > > Hans
> > >
> > > On Mon, Feb 22, 2021 at 9:53 AM Bart Maertens <ba...@know.bi>
> > > wrote:
> > >
> > >> So the discussion is basically: do we include a Hop Gui top section or
> > >> not?
> > >> In that case, the user manual more or less becomes the Hop Gui manual.
> > >>
> > >> While we're at it, we could move the 'Tools' section to the
> > >> technical manual, where the Docker documentation currently is.
> > >> The technical guide needs some cleanup anyway: getting started is
> empty
> > so
> > >> can be removed, the hop-uit docs can go as well.
> > >> The 'logo and icons' is definitely useful, but is a style guide rather
> > >> than
> > >> purely technical documentation.
> > >>
> > >>
> > >> On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <
> > >> hans.van.akelyen@gmail.com>
> > >> wrote:
> > >>
> > >> > Hi Bart,
> > >> >
> > >> > This is why I suggest removing the top level in your structure all
> > >> > together...
> > >> > 95% of what is written in the user manual is "Hop GUI" as you
> > structure
> > >> > ends up with 4 levels the users will get lost.
> > >> > Most documentation I see in the field tries to keep it at 2 levels
> > with
> > >> 3
> > >> > levels being the exception. Users don't like to dig into sub levels
> (I
> > >> know
> > >> > I don't).
> > >> > Imho everything there should be written from a gui perspective.
> > >> >
> > >> > If you go to what we have in the "pipeline" and "workflow" section
> > now,
> > >> it
> > >> > is just a placeholder for the links under it.
> > >> > That's why I added the let's add the general concept there and then
> on
> > >> > level 2 add all the "editor"/"config"/....
> > >> >
> > >> > A/B testing might be a path to follow, but then we need to gather
> more
> > >> > information than we do now and have to start analyzing it. I suggest
> > >> this
> > >> > is something for the future. I do not think we have what it takes to
> > add
> > >> > clickstream/reading info from our website at this point in time
> > >> >
> > >> > Cheers,
> > >> > Hans
> > >> >
> > >> >
> > >> > On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <
> bart.maertens@know.bi>
> > >> > wrote:
> > >> >
> > >> > > Hop users will spend almost all of their time in Hop Gui, e.g.
> > nobody
> > >> > will
> > >> > > create an action or transform outside of Hop Gui.
> > >> > > People will look for documentation where they will use and need
> it,
> > >> not
> > >> > > where it makes most sense from a conceptual or technical point of
> > >> view.
> > >> > >
> > >> > > Since the discussion is mostly around how we structure the left
> hand
> > >> TOC
> > >> > > menu,we could do some A/B testing: refer to workflow, pipeline and
> > >> other
> > >> > > docs from their own main sections in the ToC *and* from the Hop
> Gui
> > >> > > section.
> > >> > > If we measure which path users follow to get to a documentation
> > page
> > >> and
> > >> > > one turns out to be underused, we can phase it out.
> > >> > >
> > >> > >
> > >> > >
> > >> > > On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
> > >> > > hans.van.akelyen@gmail.com> wrote:
> > >> > >
> > >> > > > I also have a feeling the GUI topic is too broad and would
> contain
> > >> > > > everything making it useless...
> > >> > > > This is what happened now with the plugins section.
> > >> > > > I think we can also remove the GUI heading and just talk about
> > >> concepts
> > >> > > and
> > >> > > > as a subtopic how they are handled in the GUI.
> > >> > > >
> > >> > > > - > Workflow (general concept)
> > >> > > > - - > Creating a workflow (GUI explanation)
> > >> > > > - - > Actions
> > >> > > > - - - > Action 1
> > >> > > > - - - > Action 2
> > >> > > > ....
> > >> > > >
> > >> > > >
> > >> > > >
> > >> > > >
> > >> > > > On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
> > >> > > > <ma...@neo4j.com.invalid> wrote:
> > >> > > >
> > >> > > > > I'm not sure I like the idea of putting everything and the
> > kitchen
> > >> > sink
> > >> > > > > under "Hop GUI". Maybe we can flatten the tree a bit?
> > >> > > > > Perhaps we can have a number of top level entries like
> > Workflows,
> > >> > > > > Pipelines, Metadata, Tools, ...?
> > >> > > > > We can put the password encryption plugin under the Hop Encr
> > tool
> > >> or
> > >> > > > under
> > >> > > > > a more generic "Security" heading. It's a non-trivial concern
> > >> after
> > >> > > all.
> > >> > > > >
> > >> > > > > Cheers,
> > >> > > > > Matt
> > >> > > > >
> > >> > > > > On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <
> > >> bart.maertens@know.bi
> > >> > >
> > >> > > > > wrote:
> > >> > > > >
> > >> > > > > > Hi Hans, All,
> > >> > > > > >
> > >> > > > > > I agree moving the plugin documentation out of the plugins
> > >> category
> > >> > > is
> > >> > > > a
> > >> > > > > > necessity.
> > >> > > > > > Our initial structure was inspired by the Hop architecture,
> > >> which
> > >> > > imho
> > >> > > > > is a
> > >> > > > > > way too technical perspective.
> > >> > > > > > The documentation structure should follow how people use Hop
> > and
> > >> > > where
> > >> > > > > they
> > >> > > > > > would look for information.
> > >> > > > > >
> > >> > > > > > People will interact with transforms, actions, project &
> > >> database
> > >> > > > config
> > >> > > > > > etc almost exclusively from Hop Gui.
> > >> > > > > > Therefore, my suggestion would be to use the 2 main
> 'Workflow'
> > >> and
> > >> > > > > > 'Pipeline' sections you mentioned, but keep them in the Hop
> > Gui
> > >> > > > section.
> > >> > > > > > Something like:
> > >> > > > > > - > Hop Gui
> > >> > > > > > - - > Workflows
> > >> > > > > > - - -> Workflow Editor
> > >> > > > > > - - - > Workflow Run Configurations
> > >> > > > > > - - - > Actions
> > >> > > > > > - - - > ....
> > >> > > > > > - - > Pipelines
> > >> > > > > > - - - > Pipeline Editor
> > >> > > > > > - - - > Pipeline Run Configurations
> > >> > > > > > - - - > Transforms
> > >> > > > > > - - - > ....
> > >> > > > > > - - > Testing
> > >> > > > > > - - > Projects & Environments
> > >> > > > > > - - > Metadata
> > >> > > > > > - - - > Databases
> > >> > > > > > - - > ....
> > >> > > > > >
> > >> > > > > > For the more configuration/administration oriented tasks, we
> > >> could
> > >> > > add
> > >> > > > a
> > >> > > > > > Tools/Administration/Configuration section, something like:
> > >> > > > > > - > Tools (or Administration?)
> > >> > > > > > - - > Hop Conf
> > >> > > > > > - - > Hop Server
> > >> > > > > > - - > Hop Run
> > >> > > > > >
> > >> > > > > > I'm not sure where e.g. the password plugins would fit in,
> > since
> > >> > > > they're
> > >> > > > > > not directly development or configuration related. We could
> > keep
> > >> > > those
> > >> > > > in
> > >> > > > > > the current 'Plugins' section.
> > >> > > > > > - > Plugins
> > >> > > > > > - - > Password Plugins
> > >> > > > > >
> > >> > > > > > Regards,
> > >> > > > > > Bart
> > >> > > > > >
> > >> > > > > > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> > >> > > > > > hans.van.akelyen@gmail.com>
> > >> > > > > > wrote:
> > >> > > > > >
> > >> > > > > > > Hi Hoppers,
> > >> > > > > > >
> > >> > > > > > > I would like to restructure the documentation a bit and
> > would
> > >> > love
> > >> > > > for
> > >> > > > > > your
> > >> > > > > > > opinion on the matter.
> > >> > > > > > > Currently all our transforms and actions are gathered
> under
> > >> the
> > >> > > > plugins
> > >> > > > > > > section, this made sense when we started working on the
> > >> project
> > >> > but
> > >> > > > > from
> > >> > > > > > a
> > >> > > > > > > user perspective this is confusing.
> > >> > > > > > >
> > >> > > > > > > The suggestion is to make at least 2 large categories to
> the
> > >> > > > > > documentation
> > >> > > > > > > being "Pipeline" and "Workflow" we can then move the
> > >> > documentation
> > >> > > > that
> > >> > > > > > is
> > >> > > > > > > located under "Hop Gui" or rewrite parts of this
> > documentation
> > >> > and
> > >> > > do
> > >> > > > > > cross
> > >> > > > > > > references when needed.
> > >> > > > > > >
> > >> > > > > > > I think making these 2 large sections and adding the
> > >> > > > transforms/actions
> > >> > > > > > > here will greatly improve readability. We can still use
> the
> > >> > plugins
> > >> > > > > > section
> > >> > > > > > > too, we can use it for external plugins or
> > transforms/actions
> > >> > that
> > >> > > we
> > >> > > > > > will
> > >> > > > > > > not be adding to the default release in the future.
> > >> > > > > > >
> > >> > > > > > > Cheers,
> > >> > > > > > > Hans
> > >> > > > > > >
> > >> > > > > >
> > >> > > > >
> > >> > > > >
> > >> > > > > --
> > >> > > > > Neo4j Chief Solutions Architect
> > >> > > > > *✉ *matt.casters@neo4j.com
> > >> > > > > ☎ +32486972937
> > >> > > > >
> > >> > > >
> > >> > >
> > >> >
> > >>
> > >
> >
>
>
> --
> Neo4j Chief Solutions Architect
> *✉ *matt.casters@neo4j.com
> ☎ +32486972937
>
Re: Documentation
Posted by Bart Maertens <ba...@know.bi>.
Agreed, this is a significant improvement!
Once these changes have been pushed, I'll see if we can do a better job of
tracking which documentation pages are visited and which ones may go
unnoticed. If we don't measure, we don't know.
On Thu, Mar 11, 2021 at 9:39 AM Matt Casters <ma...@neo4j.com.invalid>
wrote:
> I really like the new structure. I'm not against leaving place-holders as
> well to remind us where documentation might be missing.
>
>
> On Wed, Mar 10, 2021 at 9:42 PM Hans Van Akelyen <
> hans.van.akelyen@gmail.com>
> wrote:
>
> > Hi All,
> >
> > I have created a first draft for the new structure for the documentation
> > and would love some feedback.
> > The new Lay out can be found here:
> > https://hop.apache.org/manual/New%20Layout/index.html
> >
> > Please note that only the structure has changed (left hand side), the
> > content does not match the structure and some links will not work as
> > expected. I would first like to have some feedback and will then proceed
> in
> > changing all the pages.
> >
> > I have a feeling the new structure is more user oriented and less
> > confusing, as a general rule of thumb I kept everything at max 3 levels
> > deep (who would dig even further? I know I wouldn't) and sorted them in
> > what I hope is a logical order.
> >
> >
> > Cheers,
> > Hans
> >
> > On Mon, 22 Feb 2021 at 10:27, Hans Van Akelyen <
> hans.van.akelyen@gmail.com
> > >
> > wrote:
> >
> > > I think we should indeed see the user manual as a user oriented and
> thus
> > > Hop GUI manual, though it can still contain concepts and more textual
> > > information needed to grasp all the concepts and components that Hop
> > > contains.
> > >
> > > The more technical information on how to use CLI and configure (server)
> > > environments should go to the technical documentation. As most users
> will
> > > not use this on a day to day basis.
> > >
> > > Cheers,
> > > Hans
> > >
> > > On Mon, Feb 22, 2021 at 9:53 AM Bart Maertens <ba...@know.bi>
> > > wrote:
> > >
> > >> So the discussion is basically: do we include a Hop Gui top section or
> > >> not?
> > >> In that case, the user manual more or less becomes the Hop Gui manual.
> > >>
> > >> While we're at it, we could move the 'Tools' section to the
> > >> technical manual, where the Docker documentation currently is.
> > >> The technical guide needs some cleanup anyway: getting started is
> empty
> > so
> > >> can be removed, the hop-uit docs can go as well.
> > >> The 'logo and icons' is definitely useful, but is a style guide rather
> > >> than
> > >> purely technical documentation.
> > >>
> > >>
> > >> On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <
> > >> hans.van.akelyen@gmail.com>
> > >> wrote:
> > >>
> > >> > Hi Bart,
> > >> >
> > >> > This is why I suggest removing the top level in your structure all
> > >> > together...
> > >> > 95% of what is written in the user manual is "Hop GUI" as you
> > structure
> > >> > ends up with 4 levels the users will get lost.
> > >> > Most documentation I see in the field tries to keep it at 2 levels
> > with
> > >> 3
> > >> > levels being the exception. Users don't like to dig into sub levels
> (I
> > >> know
> > >> > I don't).
> > >> > Imho everything there should be written from a gui perspective.
> > >> >
> > >> > If you go to what we have in the "pipeline" and "workflow" section
> > now,
> > >> it
> > >> > is just a placeholder for the links under it.
> > >> > That's why I added the let's add the general concept there and then
> on
> > >> > level 2 add all the "editor"/"config"/....
> > >> >
> > >> > A/B testing might be a path to follow, but then we need to gather
> more
> > >> > information than we do now and have to start analyzing it. I suggest
> > >> this
> > >> > is something for the future. I do not think we have what it takes to
> > add
> > >> > clickstream/reading info from our website at this point in time
> > >> >
> > >> > Cheers,
> > >> > Hans
> > >> >
> > >> >
> > >> > On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <
> bart.maertens@know.bi>
> > >> > wrote:
> > >> >
> > >> > > Hop users will spend almost all of their time in Hop Gui, e.g.
> > nobody
> > >> > will
> > >> > > create an action or transform outside of Hop Gui.
> > >> > > People will look for documentation where they will use and need
> it,
> > >> not
> > >> > > where it makes most sense from a conceptual or technical point of
> > >> view.
> > >> > >
> > >> > > Since the discussion is mostly around how we structure the left
> hand
> > >> TOC
> > >> > > menu,we could do some A/B testing: refer to workflow, pipeline and
> > >> other
> > >> > > docs from their own main sections in the ToC *and* from the Hop
> Gui
> > >> > > section.
> > >> > > If we measure which path users follow to get to a documentation
> > page
> > >> and
> > >> > > one turns out to be underused, we can phase it out.
> > >> > >
> > >> > >
> > >> > >
> > >> > > On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
> > >> > > hans.van.akelyen@gmail.com> wrote:
> > >> > >
> > >> > > > I also have a feeling the GUI topic is too broad and would
> contain
> > >> > > > everything making it useless...
> > >> > > > This is what happened now with the plugins section.
> > >> > > > I think we can also remove the GUI heading and just talk about
> > >> concepts
> > >> > > and
> > >> > > > as a subtopic how they are handled in the GUI.
> > >> > > >
> > >> > > > - > Workflow (general concept)
> > >> > > > - - > Creating a workflow (GUI explanation)
> > >> > > > - - > Actions
> > >> > > > - - - > Action 1
> > >> > > > - - - > Action 2
> > >> > > > ....
> > >> > > >
> > >> > > >
> > >> > > >
> > >> > > >
> > >> > > > On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
> > >> > > > <ma...@neo4j.com.invalid> wrote:
> > >> > > >
> > >> > > > > I'm not sure I like the idea of putting everything and the
> > kitchen
> > >> > sink
> > >> > > > > under "Hop GUI". Maybe we can flatten the tree a bit?
> > >> > > > > Perhaps we can have a number of top level entries like
> > Workflows,
> > >> > > > > Pipelines, Metadata, Tools, ...?
> > >> > > > > We can put the password encryption plugin under the Hop Encr
> > tool
> > >> or
> > >> > > > under
> > >> > > > > a more generic "Security" heading. It's a non-trivial concern
> > >> after
> > >> > > all.
> > >> > > > >
> > >> > > > > Cheers,
> > >> > > > > Matt
> > >> > > > >
> > >> > > > > On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <
> > >> bart.maertens@know.bi
> > >> > >
> > >> > > > > wrote:
> > >> > > > >
> > >> > > > > > Hi Hans, All,
> > >> > > > > >
> > >> > > > > > I agree moving the plugin documentation out of the plugins
> > >> category
> > >> > > is
> > >> > > > a
> > >> > > > > > necessity.
> > >> > > > > > Our initial structure was inspired by the Hop architecture,
> > >> which
> > >> > > imho
> > >> > > > > is a
> > >> > > > > > way too technical perspective.
> > >> > > > > > The documentation structure should follow how people use Hop
> > and
> > >> > > where
> > >> > > > > they
> > >> > > > > > would look for information.
> > >> > > > > >
> > >> > > > > > People will interact with transforms, actions, project &
> > >> database
> > >> > > > config
> > >> > > > > > etc almost exclusively from Hop Gui.
> > >> > > > > > Therefore, my suggestion would be to use the 2 main
> 'Workflow'
> > >> and
> > >> > > > > > 'Pipeline' sections you mentioned, but keep them in the Hop
> > Gui
> > >> > > > section.
> > >> > > > > > Something like:
> > >> > > > > > - > Hop Gui
> > >> > > > > > - - > Workflows
> > >> > > > > > - - -> Workflow Editor
> > >> > > > > > - - - > Workflow Run Configurations
> > >> > > > > > - - - > Actions
> > >> > > > > > - - - > ....
> > >> > > > > > - - > Pipelines
> > >> > > > > > - - - > Pipeline Editor
> > >> > > > > > - - - > Pipeline Run Configurations
> > >> > > > > > - - - > Transforms
> > >> > > > > > - - - > ....
> > >> > > > > > - - > Testing
> > >> > > > > > - - > Projects & Environments
> > >> > > > > > - - > Metadata
> > >> > > > > > - - - > Databases
> > >> > > > > > - - > ....
> > >> > > > > >
> > >> > > > > > For the more configuration/administration oriented tasks, we
> > >> could
> > >> > > add
> > >> > > > a
> > >> > > > > > Tools/Administration/Configuration section, something like:
> > >> > > > > > - > Tools (or Administration?)
> > >> > > > > > - - > Hop Conf
> > >> > > > > > - - > Hop Server
> > >> > > > > > - - > Hop Run
> > >> > > > > >
> > >> > > > > > I'm not sure where e.g. the password plugins would fit in,
> > since
> > >> > > > they're
> > >> > > > > > not directly development or configuration related. We could
> > keep
> > >> > > those
> > >> > > > in
> > >> > > > > > the current 'Plugins' section.
> > >> > > > > > - > Plugins
> > >> > > > > > - - > Password Plugins
> > >> > > > > >
> > >> > > > > > Regards,
> > >> > > > > > Bart
> > >> > > > > >
> > >> > > > > > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> > >> > > > > > hans.van.akelyen@gmail.com>
> > >> > > > > > wrote:
> > >> > > > > >
> > >> > > > > > > Hi Hoppers,
> > >> > > > > > >
> > >> > > > > > > I would like to restructure the documentation a bit and
> > would
> > >> > love
> > >> > > > for
> > >> > > > > > your
> > >> > > > > > > opinion on the matter.
> > >> > > > > > > Currently all our transforms and actions are gathered
> under
> > >> the
> > >> > > > plugins
> > >> > > > > > > section, this made sense when we started working on the
> > >> project
> > >> > but
> > >> > > > > from
> > >> > > > > > a
> > >> > > > > > > user perspective this is confusing.
> > >> > > > > > >
> > >> > > > > > > The suggestion is to make at least 2 large categories to
> the
> > >> > > > > > documentation
> > >> > > > > > > being "Pipeline" and "Workflow" we can then move the
> > >> > documentation
> > >> > > > that
> > >> > > > > > is
> > >> > > > > > > located under "Hop Gui" or rewrite parts of this
> > documentation
> > >> > and
> > >> > > do
> > >> > > > > > cross
> > >> > > > > > > references when needed.
> > >> > > > > > >
> > >> > > > > > > I think making these 2 large sections and adding the
> > >> > > > transforms/actions
> > >> > > > > > > here will greatly improve readability. We can still use
> the
> > >> > plugins
> > >> > > > > > section
> > >> > > > > > > too, we can use it for external plugins or
> > transforms/actions
> > >> > that
> > >> > > we
> > >> > > > > > will
> > >> > > > > > > not be adding to the default release in the future.
> > >> > > > > > >
> > >> > > > > > > Cheers,
> > >> > > > > > > Hans
> > >> > > > > > >
> > >> > > > > >
> > >> > > > >
> > >> > > > >
> > >> > > > > --
> > >> > > > > Neo4j Chief Solutions Architect
> > >> > > > > *✉ *matt.casters@neo4j.com
> > >> > > > > ☎ +32486972937
> > >> > > > >
> > >> > > >
> > >> > >
> > >> >
> > >>
> > >
> >
>
>
> --
> Neo4j Chief Solutions Architect
> *✉ *matt.casters@neo4j.com
> ☎ +32486972937
>
Re: Documentation
Posted by Matt Casters <ma...@neo4j.com>.
I really like the new structure. I'm not against leaving place-holders as
well to remind us where documentation might be missing.
On Wed, Mar 10, 2021 at 9:42 PM Hans Van Akelyen <ha...@gmail.com>
wrote:
> Hi All,
>
> I have created a first draft for the new structure for the documentation
> and would love some feedback.
> The new Lay out can be found here:
> https://hop.apache.org/manual/New%20Layout/index.html
>
> Please note that only the structure has changed (left hand side), the
> content does not match the structure and some links will not work as
> expected. I would first like to have some feedback and will then proceed in
> changing all the pages.
>
> I have a feeling the new structure is more user oriented and less
> confusing, as a general rule of thumb I kept everything at max 3 levels
> deep (who would dig even further? I know I wouldn't) and sorted them in
> what I hope is a logical order.
>
>
> Cheers,
> Hans
>
> On Mon, 22 Feb 2021 at 10:27, Hans Van Akelyen <hans.van.akelyen@gmail.com
> >
> wrote:
>
> > I think we should indeed see the user manual as a user oriented and thus
> > Hop GUI manual, though it can still contain concepts and more textual
> > information needed to grasp all the concepts and components that Hop
> > contains.
> >
> > The more technical information on how to use CLI and configure (server)
> > environments should go to the technical documentation. As most users will
> > not use this on a day to day basis.
> >
> > Cheers,
> > Hans
> >
> > On Mon, Feb 22, 2021 at 9:53 AM Bart Maertens <ba...@know.bi>
> > wrote:
> >
> >> So the discussion is basically: do we include a Hop Gui top section or
> >> not?
> >> In that case, the user manual more or less becomes the Hop Gui manual.
> >>
> >> While we're at it, we could move the 'Tools' section to the
> >> technical manual, where the Docker documentation currently is.
> >> The technical guide needs some cleanup anyway: getting started is empty
> so
> >> can be removed, the hop-uit docs can go as well.
> >> The 'logo and icons' is definitely useful, but is a style guide rather
> >> than
> >> purely technical documentation.
> >>
> >>
> >> On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <
> >> hans.van.akelyen@gmail.com>
> >> wrote:
> >>
> >> > Hi Bart,
> >> >
> >> > This is why I suggest removing the top level in your structure all
> >> > together...
> >> > 95% of what is written in the user manual is "Hop GUI" as you
> structure
> >> > ends up with 4 levels the users will get lost.
> >> > Most documentation I see in the field tries to keep it at 2 levels
> with
> >> 3
> >> > levels being the exception. Users don't like to dig into sub levels (I
> >> know
> >> > I don't).
> >> > Imho everything there should be written from a gui perspective.
> >> >
> >> > If you go to what we have in the "pipeline" and "workflow" section
> now,
> >> it
> >> > is just a placeholder for the links under it.
> >> > That's why I added the let's add the general concept there and then on
> >> > level 2 add all the "editor"/"config"/....
> >> >
> >> > A/B testing might be a path to follow, but then we need to gather more
> >> > information than we do now and have to start analyzing it. I suggest
> >> this
> >> > is something for the future. I do not think we have what it takes to
> add
> >> > clickstream/reading info from our website at this point in time
> >> >
> >> > Cheers,
> >> > Hans
> >> >
> >> >
> >> > On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <ba...@know.bi>
> >> > wrote:
> >> >
> >> > > Hop users will spend almost all of their time in Hop Gui, e.g.
> nobody
> >> > will
> >> > > create an action or transform outside of Hop Gui.
> >> > > People will look for documentation where they will use and need it,
> >> not
> >> > > where it makes most sense from a conceptual or technical point of
> >> view.
> >> > >
> >> > > Since the discussion is mostly around how we structure the left hand
> >> TOC
> >> > > menu,we could do some A/B testing: refer to workflow, pipeline and
> >> other
> >> > > docs from their own main sections in the ToC *and* from the Hop Gui
> >> > > section.
> >> > > If we measure which path users follow to get to a documentation
> page
> >> and
> >> > > one turns out to be underused, we can phase it out.
> >> > >
> >> > >
> >> > >
> >> > > On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
> >> > > hans.van.akelyen@gmail.com> wrote:
> >> > >
> >> > > > I also have a feeling the GUI topic is too broad and would contain
> >> > > > everything making it useless...
> >> > > > This is what happened now with the plugins section.
> >> > > > I think we can also remove the GUI heading and just talk about
> >> concepts
> >> > > and
> >> > > > as a subtopic how they are handled in the GUI.
> >> > > >
> >> > > > - > Workflow (general concept)
> >> > > > - - > Creating a workflow (GUI explanation)
> >> > > > - - > Actions
> >> > > > - - - > Action 1
> >> > > > - - - > Action 2
> >> > > > ....
> >> > > >
> >> > > >
> >> > > >
> >> > > >
> >> > > > On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
> >> > > > <ma...@neo4j.com.invalid> wrote:
> >> > > >
> >> > > > > I'm not sure I like the idea of putting everything and the
> kitchen
> >> > sink
> >> > > > > under "Hop GUI". Maybe we can flatten the tree a bit?
> >> > > > > Perhaps we can have a number of top level entries like
> Workflows,
> >> > > > > Pipelines, Metadata, Tools, ...?
> >> > > > > We can put the password encryption plugin under the Hop Encr
> tool
> >> or
> >> > > > under
> >> > > > > a more generic "Security" heading. It's a non-trivial concern
> >> after
> >> > > all.
> >> > > > >
> >> > > > > Cheers,
> >> > > > > Matt
> >> > > > >
> >> > > > > On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <
> >> bart.maertens@know.bi
> >> > >
> >> > > > > wrote:
> >> > > > >
> >> > > > > > Hi Hans, All,
> >> > > > > >
> >> > > > > > I agree moving the plugin documentation out of the plugins
> >> category
> >> > > is
> >> > > > a
> >> > > > > > necessity.
> >> > > > > > Our initial structure was inspired by the Hop architecture,
> >> which
> >> > > imho
> >> > > > > is a
> >> > > > > > way too technical perspective.
> >> > > > > > The documentation structure should follow how people use Hop
> and
> >> > > where
> >> > > > > they
> >> > > > > > would look for information.
> >> > > > > >
> >> > > > > > People will interact with transforms, actions, project &
> >> database
> >> > > > config
> >> > > > > > etc almost exclusively from Hop Gui.
> >> > > > > > Therefore, my suggestion would be to use the 2 main 'Workflow'
> >> and
> >> > > > > > 'Pipeline' sections you mentioned, but keep them in the Hop
> Gui
> >> > > > section.
> >> > > > > > Something like:
> >> > > > > > - > Hop Gui
> >> > > > > > - - > Workflows
> >> > > > > > - - -> Workflow Editor
> >> > > > > > - - - > Workflow Run Configurations
> >> > > > > > - - - > Actions
> >> > > > > > - - - > ....
> >> > > > > > - - > Pipelines
> >> > > > > > - - - > Pipeline Editor
> >> > > > > > - - - > Pipeline Run Configurations
> >> > > > > > - - - > Transforms
> >> > > > > > - - - > ....
> >> > > > > > - - > Testing
> >> > > > > > - - > Projects & Environments
> >> > > > > > - - > Metadata
> >> > > > > > - - - > Databases
> >> > > > > > - - > ....
> >> > > > > >
> >> > > > > > For the more configuration/administration oriented tasks, we
> >> could
> >> > > add
> >> > > > a
> >> > > > > > Tools/Administration/Configuration section, something like:
> >> > > > > > - > Tools (or Administration?)
> >> > > > > > - - > Hop Conf
> >> > > > > > - - > Hop Server
> >> > > > > > - - > Hop Run
> >> > > > > >
> >> > > > > > I'm not sure where e.g. the password plugins would fit in,
> since
> >> > > > they're
> >> > > > > > not directly development or configuration related. We could
> keep
> >> > > those
> >> > > > in
> >> > > > > > the current 'Plugins' section.
> >> > > > > > - > Plugins
> >> > > > > > - - > Password Plugins
> >> > > > > >
> >> > > > > > Regards,
> >> > > > > > Bart
> >> > > > > >
> >> > > > > > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> >> > > > > > hans.van.akelyen@gmail.com>
> >> > > > > > wrote:
> >> > > > > >
> >> > > > > > > Hi Hoppers,
> >> > > > > > >
> >> > > > > > > I would like to restructure the documentation a bit and
> would
> >> > love
> >> > > > for
> >> > > > > > your
> >> > > > > > > opinion on the matter.
> >> > > > > > > Currently all our transforms and actions are gathered under
> >> the
> >> > > > plugins
> >> > > > > > > section, this made sense when we started working on the
> >> project
> >> > but
> >> > > > > from
> >> > > > > > a
> >> > > > > > > user perspective this is confusing.
> >> > > > > > >
> >> > > > > > > The suggestion is to make at least 2 large categories to the
> >> > > > > > documentation
> >> > > > > > > being "Pipeline" and "Workflow" we can then move the
> >> > documentation
> >> > > > that
> >> > > > > > is
> >> > > > > > > located under "Hop Gui" or rewrite parts of this
> documentation
> >> > and
> >> > > do
> >> > > > > > cross
> >> > > > > > > references when needed.
> >> > > > > > >
> >> > > > > > > I think making these 2 large sections and adding the
> >> > > > transforms/actions
> >> > > > > > > here will greatly improve readability. We can still use the
> >> > plugins
> >> > > > > > section
> >> > > > > > > too, we can use it for external plugins or
> transforms/actions
> >> > that
> >> > > we
> >> > > > > > will
> >> > > > > > > not be adding to the default release in the future.
> >> > > > > > >
> >> > > > > > > Cheers,
> >> > > > > > > Hans
> >> > > > > > >
> >> > > > > >
> >> > > > >
> >> > > > >
> >> > > > > --
> >> > > > > Neo4j Chief Solutions Architect
> >> > > > > *✉ *matt.casters@neo4j.com
> >> > > > > ☎ +32486972937
> >> > > > >
> >> > > >
> >> > >
> >> >
> >>
> >
>
--
Neo4j Chief Solutions Architect
*✉ *matt.casters@neo4j.com
☎ +32486972937
Re: Documentation
Posted by Matt Casters <ma...@neo4j.com.INVALID>.
I really like the new structure. I'm not against leaving place-holders as
well to remind us where documentation might be missing.
On Wed, Mar 10, 2021 at 9:42 PM Hans Van Akelyen <ha...@gmail.com>
wrote:
> Hi All,
>
> I have created a first draft for the new structure for the documentation
> and would love some feedback.
> The new Lay out can be found here:
> https://hop.apache.org/manual/New%20Layout/index.html
>
> Please note that only the structure has changed (left hand side), the
> content does not match the structure and some links will not work as
> expected. I would first like to have some feedback and will then proceed in
> changing all the pages.
>
> I have a feeling the new structure is more user oriented and less
> confusing, as a general rule of thumb I kept everything at max 3 levels
> deep (who would dig even further? I know I wouldn't) and sorted them in
> what I hope is a logical order.
>
>
> Cheers,
> Hans
>
> On Mon, 22 Feb 2021 at 10:27, Hans Van Akelyen <hans.van.akelyen@gmail.com
> >
> wrote:
>
> > I think we should indeed see the user manual as a user oriented and thus
> > Hop GUI manual, though it can still contain concepts and more textual
> > information needed to grasp all the concepts and components that Hop
> > contains.
> >
> > The more technical information on how to use CLI and configure (server)
> > environments should go to the technical documentation. As most users will
> > not use this on a day to day basis.
> >
> > Cheers,
> > Hans
> >
> > On Mon, Feb 22, 2021 at 9:53 AM Bart Maertens <ba...@know.bi>
> > wrote:
> >
> >> So the discussion is basically: do we include a Hop Gui top section or
> >> not?
> >> In that case, the user manual more or less becomes the Hop Gui manual.
> >>
> >> While we're at it, we could move the 'Tools' section to the
> >> technical manual, where the Docker documentation currently is.
> >> The technical guide needs some cleanup anyway: getting started is empty
> so
> >> can be removed, the hop-uit docs can go as well.
> >> The 'logo and icons' is definitely useful, but is a style guide rather
> >> than
> >> purely technical documentation.
> >>
> >>
> >> On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <
> >> hans.van.akelyen@gmail.com>
> >> wrote:
> >>
> >> > Hi Bart,
> >> >
> >> > This is why I suggest removing the top level in your structure all
> >> > together...
> >> > 95% of what is written in the user manual is "Hop GUI" as you
> structure
> >> > ends up with 4 levels the users will get lost.
> >> > Most documentation I see in the field tries to keep it at 2 levels
> with
> >> 3
> >> > levels being the exception. Users don't like to dig into sub levels (I
> >> know
> >> > I don't).
> >> > Imho everything there should be written from a gui perspective.
> >> >
> >> > If you go to what we have in the "pipeline" and "workflow" section
> now,
> >> it
> >> > is just a placeholder for the links under it.
> >> > That's why I added the let's add the general concept there and then on
> >> > level 2 add all the "editor"/"config"/....
> >> >
> >> > A/B testing might be a path to follow, but then we need to gather more
> >> > information than we do now and have to start analyzing it. I suggest
> >> this
> >> > is something for the future. I do not think we have what it takes to
> add
> >> > clickstream/reading info from our website at this point in time
> >> >
> >> > Cheers,
> >> > Hans
> >> >
> >> >
> >> > On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <ba...@know.bi>
> >> > wrote:
> >> >
> >> > > Hop users will spend almost all of their time in Hop Gui, e.g.
> nobody
> >> > will
> >> > > create an action or transform outside of Hop Gui.
> >> > > People will look for documentation where they will use and need it,
> >> not
> >> > > where it makes most sense from a conceptual or technical point of
> >> view.
> >> > >
> >> > > Since the discussion is mostly around how we structure the left hand
> >> TOC
> >> > > menu,we could do some A/B testing: refer to workflow, pipeline and
> >> other
> >> > > docs from their own main sections in the ToC *and* from the Hop Gui
> >> > > section.
> >> > > If we measure which path users follow to get to a documentation
> page
> >> and
> >> > > one turns out to be underused, we can phase it out.
> >> > >
> >> > >
> >> > >
> >> > > On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
> >> > > hans.van.akelyen@gmail.com> wrote:
> >> > >
> >> > > > I also have a feeling the GUI topic is too broad and would contain
> >> > > > everything making it useless...
> >> > > > This is what happened now with the plugins section.
> >> > > > I think we can also remove the GUI heading and just talk about
> >> concepts
> >> > > and
> >> > > > as a subtopic how they are handled in the GUI.
> >> > > >
> >> > > > - > Workflow (general concept)
> >> > > > - - > Creating a workflow (GUI explanation)
> >> > > > - - > Actions
> >> > > > - - - > Action 1
> >> > > > - - - > Action 2
> >> > > > ....
> >> > > >
> >> > > >
> >> > > >
> >> > > >
> >> > > > On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
> >> > > > <ma...@neo4j.com.invalid> wrote:
> >> > > >
> >> > > > > I'm not sure I like the idea of putting everything and the
> kitchen
> >> > sink
> >> > > > > under "Hop GUI". Maybe we can flatten the tree a bit?
> >> > > > > Perhaps we can have a number of top level entries like
> Workflows,
> >> > > > > Pipelines, Metadata, Tools, ...?
> >> > > > > We can put the password encryption plugin under the Hop Encr
> tool
> >> or
> >> > > > under
> >> > > > > a more generic "Security" heading. It's a non-trivial concern
> >> after
> >> > > all.
> >> > > > >
> >> > > > > Cheers,
> >> > > > > Matt
> >> > > > >
> >> > > > > On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <
> >> bart.maertens@know.bi
> >> > >
> >> > > > > wrote:
> >> > > > >
> >> > > > > > Hi Hans, All,
> >> > > > > >
> >> > > > > > I agree moving the plugin documentation out of the plugins
> >> category
> >> > > is
> >> > > > a
> >> > > > > > necessity.
> >> > > > > > Our initial structure was inspired by the Hop architecture,
> >> which
> >> > > imho
> >> > > > > is a
> >> > > > > > way too technical perspective.
> >> > > > > > The documentation structure should follow how people use Hop
> and
> >> > > where
> >> > > > > they
> >> > > > > > would look for information.
> >> > > > > >
> >> > > > > > People will interact with transforms, actions, project &
> >> database
> >> > > > config
> >> > > > > > etc almost exclusively from Hop Gui.
> >> > > > > > Therefore, my suggestion would be to use the 2 main 'Workflow'
> >> and
> >> > > > > > 'Pipeline' sections you mentioned, but keep them in the Hop
> Gui
> >> > > > section.
> >> > > > > > Something like:
> >> > > > > > - > Hop Gui
> >> > > > > > - - > Workflows
> >> > > > > > - - -> Workflow Editor
> >> > > > > > - - - > Workflow Run Configurations
> >> > > > > > - - - > Actions
> >> > > > > > - - - > ....
> >> > > > > > - - > Pipelines
> >> > > > > > - - - > Pipeline Editor
> >> > > > > > - - - > Pipeline Run Configurations
> >> > > > > > - - - > Transforms
> >> > > > > > - - - > ....
> >> > > > > > - - > Testing
> >> > > > > > - - > Projects & Environments
> >> > > > > > - - > Metadata
> >> > > > > > - - - > Databases
> >> > > > > > - - > ....
> >> > > > > >
> >> > > > > > For the more configuration/administration oriented tasks, we
> >> could
> >> > > add
> >> > > > a
> >> > > > > > Tools/Administration/Configuration section, something like:
> >> > > > > > - > Tools (or Administration?)
> >> > > > > > - - > Hop Conf
> >> > > > > > - - > Hop Server
> >> > > > > > - - > Hop Run
> >> > > > > >
> >> > > > > > I'm not sure where e.g. the password plugins would fit in,
> since
> >> > > > they're
> >> > > > > > not directly development or configuration related. We could
> keep
> >> > > those
> >> > > > in
> >> > > > > > the current 'Plugins' section.
> >> > > > > > - > Plugins
> >> > > > > > - - > Password Plugins
> >> > > > > >
> >> > > > > > Regards,
> >> > > > > > Bart
> >> > > > > >
> >> > > > > > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> >> > > > > > hans.van.akelyen@gmail.com>
> >> > > > > > wrote:
> >> > > > > >
> >> > > > > > > Hi Hoppers,
> >> > > > > > >
> >> > > > > > > I would like to restructure the documentation a bit and
> would
> >> > love
> >> > > > for
> >> > > > > > your
> >> > > > > > > opinion on the matter.
> >> > > > > > > Currently all our transforms and actions are gathered under
> >> the
> >> > > > plugins
> >> > > > > > > section, this made sense when we started working on the
> >> project
> >> > but
> >> > > > > from
> >> > > > > > a
> >> > > > > > > user perspective this is confusing.
> >> > > > > > >
> >> > > > > > > The suggestion is to make at least 2 large categories to the
> >> > > > > > documentation
> >> > > > > > > being "Pipeline" and "Workflow" we can then move the
> >> > documentation
> >> > > > that
> >> > > > > > is
> >> > > > > > > located under "Hop Gui" or rewrite parts of this
> documentation
> >> > and
> >> > > do
> >> > > > > > cross
> >> > > > > > > references when needed.
> >> > > > > > >
> >> > > > > > > I think making these 2 large sections and adding the
> >> > > > transforms/actions
> >> > > > > > > here will greatly improve readability. We can still use the
> >> > plugins
> >> > > > > > section
> >> > > > > > > too, we can use it for external plugins or
> transforms/actions
> >> > that
> >> > > we
> >> > > > > > will
> >> > > > > > > not be adding to the default release in the future.
> >> > > > > > >
> >> > > > > > > Cheers,
> >> > > > > > > Hans
> >> > > > > > >
> >> > > > > >
> >> > > > >
> >> > > > >
> >> > > > > --
> >> > > > > Neo4j Chief Solutions Architect
> >> > > > > *✉ *matt.casters@neo4j.com
> >> > > > > ☎ +32486972937
> >> > > > >
> >> > > >
> >> > >
> >> >
> >>
> >
>
--
Neo4j Chief Solutions Architect
*✉ *matt.casters@neo4j.com
☎ +32486972937
Re: Documentation
Posted by Hans Van Akelyen <ha...@gmail.com>.
Hi All,
I have created a first draft for the new structure for the documentation
and would love some feedback.
The new Lay out can be found here:
https://hop.apache.org/manual/New%20Layout/index.html
Please note that only the structure has changed (left hand side), the
content does not match the structure and some links will not work as
expected. I would first like to have some feedback and will then proceed in
changing all the pages.
I have a feeling the new structure is more user oriented and less
confusing, as a general rule of thumb I kept everything at max 3 levels
deep (who would dig even further? I know I wouldn't) and sorted them in
what I hope is a logical order.
Cheers,
Hans
On Mon, 22 Feb 2021 at 10:27, Hans Van Akelyen <ha...@gmail.com>
wrote:
> I think we should indeed see the user manual as a user oriented and thus
> Hop GUI manual, though it can still contain concepts and more textual
> information needed to grasp all the concepts and components that Hop
> contains.
>
> The more technical information on how to use CLI and configure (server)
> environments should go to the technical documentation. As most users will
> not use this on a day to day basis.
>
> Cheers,
> Hans
>
> On Mon, Feb 22, 2021 at 9:53 AM Bart Maertens <ba...@know.bi>
> wrote:
>
>> So the discussion is basically: do we include a Hop Gui top section or
>> not?
>> In that case, the user manual more or less becomes the Hop Gui manual.
>>
>> While we're at it, we could move the 'Tools' section to the
>> technical manual, where the Docker documentation currently is.
>> The technical guide needs some cleanup anyway: getting started is empty so
>> can be removed, the hop-uit docs can go as well.
>> The 'logo and icons' is definitely useful, but is a style guide rather
>> than
>> purely technical documentation.
>>
>>
>> On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <
>> hans.van.akelyen@gmail.com>
>> wrote:
>>
>> > Hi Bart,
>> >
>> > This is why I suggest removing the top level in your structure all
>> > together...
>> > 95% of what is written in the user manual is "Hop GUI" as you structure
>> > ends up with 4 levels the users will get lost.
>> > Most documentation I see in the field tries to keep it at 2 levels with
>> 3
>> > levels being the exception. Users don't like to dig into sub levels (I
>> know
>> > I don't).
>> > Imho everything there should be written from a gui perspective.
>> >
>> > If you go to what we have in the "pipeline" and "workflow" section now,
>> it
>> > is just a placeholder for the links under it.
>> > That's why I added the let's add the general concept there and then on
>> > level 2 add all the "editor"/"config"/....
>> >
>> > A/B testing might be a path to follow, but then we need to gather more
>> > information than we do now and have to start analyzing it. I suggest
>> this
>> > is something for the future. I do not think we have what it takes to add
>> > clickstream/reading info from our website at this point in time
>> >
>> > Cheers,
>> > Hans
>> >
>> >
>> > On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <ba...@know.bi>
>> > wrote:
>> >
>> > > Hop users will spend almost all of their time in Hop Gui, e.g. nobody
>> > will
>> > > create an action or transform outside of Hop Gui.
>> > > People will look for documentation where they will use and need it,
>> not
>> > > where it makes most sense from a conceptual or technical point of
>> view.
>> > >
>> > > Since the discussion is mostly around how we structure the left hand
>> TOC
>> > > menu,we could do some A/B testing: refer to workflow, pipeline and
>> other
>> > > docs from their own main sections in the ToC *and* from the Hop Gui
>> > > section.
>> > > If we measure which path users follow to get to a documentation page
>> and
>> > > one turns out to be underused, we can phase it out.
>> > >
>> > >
>> > >
>> > > On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
>> > > hans.van.akelyen@gmail.com> wrote:
>> > >
>> > > > I also have a feeling the GUI topic is too broad and would contain
>> > > > everything making it useless...
>> > > > This is what happened now with the plugins section.
>> > > > I think we can also remove the GUI heading and just talk about
>> concepts
>> > > and
>> > > > as a subtopic how they are handled in the GUI.
>> > > >
>> > > > - > Workflow (general concept)
>> > > > - - > Creating a workflow (GUI explanation)
>> > > > - - > Actions
>> > > > - - - > Action 1
>> > > > - - - > Action 2
>> > > > ....
>> > > >
>> > > >
>> > > >
>> > > >
>> > > > On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
>> > > > <ma...@neo4j.com.invalid> wrote:
>> > > >
>> > > > > I'm not sure I like the idea of putting everything and the kitchen
>> > sink
>> > > > > under "Hop GUI". Maybe we can flatten the tree a bit?
>> > > > > Perhaps we can have a number of top level entries like Workflows,
>> > > > > Pipelines, Metadata, Tools, ...?
>> > > > > We can put the password encryption plugin under the Hop Encr tool
>> or
>> > > > under
>> > > > > a more generic "Security" heading. It's a non-trivial concern
>> after
>> > > all.
>> > > > >
>> > > > > Cheers,
>> > > > > Matt
>> > > > >
>> > > > > On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <
>> bart.maertens@know.bi
>> > >
>> > > > > wrote:
>> > > > >
>> > > > > > Hi Hans, All,
>> > > > > >
>> > > > > > I agree moving the plugin documentation out of the plugins
>> category
>> > > is
>> > > > a
>> > > > > > necessity.
>> > > > > > Our initial structure was inspired by the Hop architecture,
>> which
>> > > imho
>> > > > > is a
>> > > > > > way too technical perspective.
>> > > > > > The documentation structure should follow how people use Hop and
>> > > where
>> > > > > they
>> > > > > > would look for information.
>> > > > > >
>> > > > > > People will interact with transforms, actions, project &
>> database
>> > > > config
>> > > > > > etc almost exclusively from Hop Gui.
>> > > > > > Therefore, my suggestion would be to use the 2 main 'Workflow'
>> and
>> > > > > > 'Pipeline' sections you mentioned, but keep them in the Hop Gui
>> > > > section.
>> > > > > > Something like:
>> > > > > > - > Hop Gui
>> > > > > > - - > Workflows
>> > > > > > - - -> Workflow Editor
>> > > > > > - - - > Workflow Run Configurations
>> > > > > > - - - > Actions
>> > > > > > - - - > ....
>> > > > > > - - > Pipelines
>> > > > > > - - - > Pipeline Editor
>> > > > > > - - - > Pipeline Run Configurations
>> > > > > > - - - > Transforms
>> > > > > > - - - > ....
>> > > > > > - - > Testing
>> > > > > > - - > Projects & Environments
>> > > > > > - - > Metadata
>> > > > > > - - - > Databases
>> > > > > > - - > ....
>> > > > > >
>> > > > > > For the more configuration/administration oriented tasks, we
>> could
>> > > add
>> > > > a
>> > > > > > Tools/Administration/Configuration section, something like:
>> > > > > > - > Tools (or Administration?)
>> > > > > > - - > Hop Conf
>> > > > > > - - > Hop Server
>> > > > > > - - > Hop Run
>> > > > > >
>> > > > > > I'm not sure where e.g. the password plugins would fit in, since
>> > > > they're
>> > > > > > not directly development or configuration related. We could keep
>> > > those
>> > > > in
>> > > > > > the current 'Plugins' section.
>> > > > > > - > Plugins
>> > > > > > - - > Password Plugins
>> > > > > >
>> > > > > > Regards,
>> > > > > > Bart
>> > > > > >
>> > > > > > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
>> > > > > > hans.van.akelyen@gmail.com>
>> > > > > > wrote:
>> > > > > >
>> > > > > > > Hi Hoppers,
>> > > > > > >
>> > > > > > > I would like to restructure the documentation a bit and would
>> > love
>> > > > for
>> > > > > > your
>> > > > > > > opinion on the matter.
>> > > > > > > Currently all our transforms and actions are gathered under
>> the
>> > > > plugins
>> > > > > > > section, this made sense when we started working on the
>> project
>> > but
>> > > > > from
>> > > > > > a
>> > > > > > > user perspective this is confusing.
>> > > > > > >
>> > > > > > > The suggestion is to make at least 2 large categories to the
>> > > > > > documentation
>> > > > > > > being "Pipeline" and "Workflow" we can then move the
>> > documentation
>> > > > that
>> > > > > > is
>> > > > > > > located under "Hop Gui" or rewrite parts of this documentation
>> > and
>> > > do
>> > > > > > cross
>> > > > > > > references when needed.
>> > > > > > >
>> > > > > > > I think making these 2 large sections and adding the
>> > > > transforms/actions
>> > > > > > > here will greatly improve readability. We can still use the
>> > plugins
>> > > > > > section
>> > > > > > > too, we can use it for external plugins or transforms/actions
>> > that
>> > > we
>> > > > > > will
>> > > > > > > not be adding to the default release in the future.
>> > > > > > >
>> > > > > > > Cheers,
>> > > > > > > Hans
>> > > > > > >
>> > > > > >
>> > > > >
>> > > > >
>> > > > > --
>> > > > > Neo4j Chief Solutions Architect
>> > > > > *✉ *matt.casters@neo4j.com
>> > > > > ☎ +32486972937
>> > > > >
>> > > >
>> > >
>> >
>>
>
Re: Documentation
Posted by Hans Van Akelyen <ha...@gmail.com>.
Hi All,
I have created a first draft for the new structure for the documentation
and would love some feedback.
The new Lay out can be found here:
https://hop.apache.org/manual/New%20Layout/index.html
Please note that only the structure has changed (left hand side), the
content does not match the structure and some links will not work as
expected. I would first like to have some feedback and will then proceed in
changing all the pages.
I have a feeling the new structure is more user oriented and less
confusing, as a general rule of thumb I kept everything at max 3 levels
deep (who would dig even further? I know I wouldn't) and sorted them in
what I hope is a logical order.
Cheers,
Hans
On Mon, 22 Feb 2021 at 10:27, Hans Van Akelyen <ha...@gmail.com>
wrote:
> I think we should indeed see the user manual as a user oriented and thus
> Hop GUI manual, though it can still contain concepts and more textual
> information needed to grasp all the concepts and components that Hop
> contains.
>
> The more technical information on how to use CLI and configure (server)
> environments should go to the technical documentation. As most users will
> not use this on a day to day basis.
>
> Cheers,
> Hans
>
> On Mon, Feb 22, 2021 at 9:53 AM Bart Maertens <ba...@know.bi>
> wrote:
>
>> So the discussion is basically: do we include a Hop Gui top section or
>> not?
>> In that case, the user manual more or less becomes the Hop Gui manual.
>>
>> While we're at it, we could move the 'Tools' section to the
>> technical manual, where the Docker documentation currently is.
>> The technical guide needs some cleanup anyway: getting started is empty so
>> can be removed, the hop-uit docs can go as well.
>> The 'logo and icons' is definitely useful, but is a style guide rather
>> than
>> purely technical documentation.
>>
>>
>> On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <
>> hans.van.akelyen@gmail.com>
>> wrote:
>>
>> > Hi Bart,
>> >
>> > This is why I suggest removing the top level in your structure all
>> > together...
>> > 95% of what is written in the user manual is "Hop GUI" as you structure
>> > ends up with 4 levels the users will get lost.
>> > Most documentation I see in the field tries to keep it at 2 levels with
>> 3
>> > levels being the exception. Users don't like to dig into sub levels (I
>> know
>> > I don't).
>> > Imho everything there should be written from a gui perspective.
>> >
>> > If you go to what we have in the "pipeline" and "workflow" section now,
>> it
>> > is just a placeholder for the links under it.
>> > That's why I added the let's add the general concept there and then on
>> > level 2 add all the "editor"/"config"/....
>> >
>> > A/B testing might be a path to follow, but then we need to gather more
>> > information than we do now and have to start analyzing it. I suggest
>> this
>> > is something for the future. I do not think we have what it takes to add
>> > clickstream/reading info from our website at this point in time
>> >
>> > Cheers,
>> > Hans
>> >
>> >
>> > On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <ba...@know.bi>
>> > wrote:
>> >
>> > > Hop users will spend almost all of their time in Hop Gui, e.g. nobody
>> > will
>> > > create an action or transform outside of Hop Gui.
>> > > People will look for documentation where they will use and need it,
>> not
>> > > where it makes most sense from a conceptual or technical point of
>> view.
>> > >
>> > > Since the discussion is mostly around how we structure the left hand
>> TOC
>> > > menu,we could do some A/B testing: refer to workflow, pipeline and
>> other
>> > > docs from their own main sections in the ToC *and* from the Hop Gui
>> > > section.
>> > > If we measure which path users follow to get to a documentation page
>> and
>> > > one turns out to be underused, we can phase it out.
>> > >
>> > >
>> > >
>> > > On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
>> > > hans.van.akelyen@gmail.com> wrote:
>> > >
>> > > > I also have a feeling the GUI topic is too broad and would contain
>> > > > everything making it useless...
>> > > > This is what happened now with the plugins section.
>> > > > I think we can also remove the GUI heading and just talk about
>> concepts
>> > > and
>> > > > as a subtopic how they are handled in the GUI.
>> > > >
>> > > > - > Workflow (general concept)
>> > > > - - > Creating a workflow (GUI explanation)
>> > > > - - > Actions
>> > > > - - - > Action 1
>> > > > - - - > Action 2
>> > > > ....
>> > > >
>> > > >
>> > > >
>> > > >
>> > > > On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
>> > > > <ma...@neo4j.com.invalid> wrote:
>> > > >
>> > > > > I'm not sure I like the idea of putting everything and the kitchen
>> > sink
>> > > > > under "Hop GUI". Maybe we can flatten the tree a bit?
>> > > > > Perhaps we can have a number of top level entries like Workflows,
>> > > > > Pipelines, Metadata, Tools, ...?
>> > > > > We can put the password encryption plugin under the Hop Encr tool
>> or
>> > > > under
>> > > > > a more generic "Security" heading. It's a non-trivial concern
>> after
>> > > all.
>> > > > >
>> > > > > Cheers,
>> > > > > Matt
>> > > > >
>> > > > > On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <
>> bart.maertens@know.bi
>> > >
>> > > > > wrote:
>> > > > >
>> > > > > > Hi Hans, All,
>> > > > > >
>> > > > > > I agree moving the plugin documentation out of the plugins
>> category
>> > > is
>> > > > a
>> > > > > > necessity.
>> > > > > > Our initial structure was inspired by the Hop architecture,
>> which
>> > > imho
>> > > > > is a
>> > > > > > way too technical perspective.
>> > > > > > The documentation structure should follow how people use Hop and
>> > > where
>> > > > > they
>> > > > > > would look for information.
>> > > > > >
>> > > > > > People will interact with transforms, actions, project &
>> database
>> > > > config
>> > > > > > etc almost exclusively from Hop Gui.
>> > > > > > Therefore, my suggestion would be to use the 2 main 'Workflow'
>> and
>> > > > > > 'Pipeline' sections you mentioned, but keep them in the Hop Gui
>> > > > section.
>> > > > > > Something like:
>> > > > > > - > Hop Gui
>> > > > > > - - > Workflows
>> > > > > > - - -> Workflow Editor
>> > > > > > - - - > Workflow Run Configurations
>> > > > > > - - - > Actions
>> > > > > > - - - > ....
>> > > > > > - - > Pipelines
>> > > > > > - - - > Pipeline Editor
>> > > > > > - - - > Pipeline Run Configurations
>> > > > > > - - - > Transforms
>> > > > > > - - - > ....
>> > > > > > - - > Testing
>> > > > > > - - > Projects & Environments
>> > > > > > - - > Metadata
>> > > > > > - - - > Databases
>> > > > > > - - > ....
>> > > > > >
>> > > > > > For the more configuration/administration oriented tasks, we
>> could
>> > > add
>> > > > a
>> > > > > > Tools/Administration/Configuration section, something like:
>> > > > > > - > Tools (or Administration?)
>> > > > > > - - > Hop Conf
>> > > > > > - - > Hop Server
>> > > > > > - - > Hop Run
>> > > > > >
>> > > > > > I'm not sure where e.g. the password plugins would fit in, since
>> > > > they're
>> > > > > > not directly development or configuration related. We could keep
>> > > those
>> > > > in
>> > > > > > the current 'Plugins' section.
>> > > > > > - > Plugins
>> > > > > > - - > Password Plugins
>> > > > > >
>> > > > > > Regards,
>> > > > > > Bart
>> > > > > >
>> > > > > > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
>> > > > > > hans.van.akelyen@gmail.com>
>> > > > > > wrote:
>> > > > > >
>> > > > > > > Hi Hoppers,
>> > > > > > >
>> > > > > > > I would like to restructure the documentation a bit and would
>> > love
>> > > > for
>> > > > > > your
>> > > > > > > opinion on the matter.
>> > > > > > > Currently all our transforms and actions are gathered under
>> the
>> > > > plugins
>> > > > > > > section, this made sense when we started working on the
>> project
>> > but
>> > > > > from
>> > > > > > a
>> > > > > > > user perspective this is confusing.
>> > > > > > >
>> > > > > > > The suggestion is to make at least 2 large categories to the
>> > > > > > documentation
>> > > > > > > being "Pipeline" and "Workflow" we can then move the
>> > documentation
>> > > > that
>> > > > > > is
>> > > > > > > located under "Hop Gui" or rewrite parts of this documentation
>> > and
>> > > do
>> > > > > > cross
>> > > > > > > references when needed.
>> > > > > > >
>> > > > > > > I think making these 2 large sections and adding the
>> > > > transforms/actions
>> > > > > > > here will greatly improve readability. We can still use the
>> > plugins
>> > > > > > section
>> > > > > > > too, we can use it for external plugins or transforms/actions
>> > that
>> > > we
>> > > > > > will
>> > > > > > > not be adding to the default release in the future.
>> > > > > > >
>> > > > > > > Cheers,
>> > > > > > > Hans
>> > > > > > >
>> > > > > >
>> > > > >
>> > > > >
>> > > > > --
>> > > > > Neo4j Chief Solutions Architect
>> > > > > *✉ *matt.casters@neo4j.com
>> > > > > ☎ +32486972937
>> > > > >
>> > > >
>> > >
>> >
>>
>
Re: Documentation
Posted by Hans Van Akelyen <ha...@gmail.com>.
I think we should indeed see the user manual as a user oriented and thus
Hop GUI manual, though it can still contain concepts and more textual
information needed to grasp all the concepts and components that Hop
contains.
The more technical information on how to use CLI and configure (server)
environments should go to the technical documentation. As most users will
not use this on a day to day basis.
Cheers,
Hans
On Mon, Feb 22, 2021 at 9:53 AM Bart Maertens <ba...@know.bi> wrote:
> So the discussion is basically: do we include a Hop Gui top section or not?
> In that case, the user manual more or less becomes the Hop Gui manual.
>
> While we're at it, we could move the 'Tools' section to the
> technical manual, where the Docker documentation currently is.
> The technical guide needs some cleanup anyway: getting started is empty so
> can be removed, the hop-uit docs can go as well.
> The 'logo and icons' is definitely useful, but is a style guide rather than
> purely technical documentation.
>
>
> On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <
> hans.van.akelyen@gmail.com>
> wrote:
>
> > Hi Bart,
> >
> > This is why I suggest removing the top level in your structure all
> > together...
> > 95% of what is written in the user manual is "Hop GUI" as you structure
> > ends up with 4 levels the users will get lost.
> > Most documentation I see in the field tries to keep it at 2 levels with 3
> > levels being the exception. Users don't like to dig into sub levels (I
> know
> > I don't).
> > Imho everything there should be written from a gui perspective.
> >
> > If you go to what we have in the "pipeline" and "workflow" section now,
> it
> > is just a placeholder for the links under it.
> > That's why I added the let's add the general concept there and then on
> > level 2 add all the "editor"/"config"/....
> >
> > A/B testing might be a path to follow, but then we need to gather more
> > information than we do now and have to start analyzing it. I suggest this
> > is something for the future. I do not think we have what it takes to add
> > clickstream/reading info from our website at this point in time
> >
> > Cheers,
> > Hans
> >
> >
> > On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <ba...@know.bi>
> > wrote:
> >
> > > Hop users will spend almost all of their time in Hop Gui, e.g. nobody
> > will
> > > create an action or transform outside of Hop Gui.
> > > People will look for documentation where they will use and need it, not
> > > where it makes most sense from a conceptual or technical point of view.
> > >
> > > Since the discussion is mostly around how we structure the left hand
> TOC
> > > menu,we could do some A/B testing: refer to workflow, pipeline and
> other
> > > docs from their own main sections in the ToC *and* from the Hop Gui
> > > section.
> > > If we measure which path users follow to get to a documentation page
> and
> > > one turns out to be underused, we can phase it out.
> > >
> > >
> > >
> > > On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
> > > hans.van.akelyen@gmail.com> wrote:
> > >
> > > > I also have a feeling the GUI topic is too broad and would contain
> > > > everything making it useless...
> > > > This is what happened now with the plugins section.
> > > > I think we can also remove the GUI heading and just talk about
> concepts
> > > and
> > > > as a subtopic how they are handled in the GUI.
> > > >
> > > > - > Workflow (general concept)
> > > > - - > Creating a workflow (GUI explanation)
> > > > - - > Actions
> > > > - - - > Action 1
> > > > - - - > Action 2
> > > > ....
> > > >
> > > >
> > > >
> > > >
> > > > On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
> > > > <ma...@neo4j.com.invalid> wrote:
> > > >
> > > > > I'm not sure I like the idea of putting everything and the kitchen
> > sink
> > > > > under "Hop GUI". Maybe we can flatten the tree a bit?
> > > > > Perhaps we can have a number of top level entries like Workflows,
> > > > > Pipelines, Metadata, Tools, ...?
> > > > > We can put the password encryption plugin under the Hop Encr tool
> or
> > > > under
> > > > > a more generic "Security" heading. It's a non-trivial concern
> after
> > > all.
> > > > >
> > > > > Cheers,
> > > > > Matt
> > > > >
> > > > > On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <
> bart.maertens@know.bi
> > >
> > > > > wrote:
> > > > >
> > > > > > Hi Hans, All,
> > > > > >
> > > > > > I agree moving the plugin documentation out of the plugins
> category
> > > is
> > > > a
> > > > > > necessity.
> > > > > > Our initial structure was inspired by the Hop architecture, which
> > > imho
> > > > > is a
> > > > > > way too technical perspective.
> > > > > > The documentation structure should follow how people use Hop and
> > > where
> > > > > they
> > > > > > would look for information.
> > > > > >
> > > > > > People will interact with transforms, actions, project & database
> > > > config
> > > > > > etc almost exclusively from Hop Gui.
> > > > > > Therefore, my suggestion would be to use the 2 main 'Workflow'
> and
> > > > > > 'Pipeline' sections you mentioned, but keep them in the Hop Gui
> > > > section.
> > > > > > Something like:
> > > > > > - > Hop Gui
> > > > > > - - > Workflows
> > > > > > - - -> Workflow Editor
> > > > > > - - - > Workflow Run Configurations
> > > > > > - - - > Actions
> > > > > > - - - > ....
> > > > > > - - > Pipelines
> > > > > > - - - > Pipeline Editor
> > > > > > - - - > Pipeline Run Configurations
> > > > > > - - - > Transforms
> > > > > > - - - > ....
> > > > > > - - > Testing
> > > > > > - - > Projects & Environments
> > > > > > - - > Metadata
> > > > > > - - - > Databases
> > > > > > - - > ....
> > > > > >
> > > > > > For the more configuration/administration oriented tasks, we
> could
> > > add
> > > > a
> > > > > > Tools/Administration/Configuration section, something like:
> > > > > > - > Tools (or Administration?)
> > > > > > - - > Hop Conf
> > > > > > - - > Hop Server
> > > > > > - - > Hop Run
> > > > > >
> > > > > > I'm not sure where e.g. the password plugins would fit in, since
> > > > they're
> > > > > > not directly development or configuration related. We could keep
> > > those
> > > > in
> > > > > > the current 'Plugins' section.
> > > > > > - > Plugins
> > > > > > - - > Password Plugins
> > > > > >
> > > > > > Regards,
> > > > > > Bart
> > > > > >
> > > > > > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> > > > > > hans.van.akelyen@gmail.com>
> > > > > > wrote:
> > > > > >
> > > > > > > Hi Hoppers,
> > > > > > >
> > > > > > > I would like to restructure the documentation a bit and would
> > love
> > > > for
> > > > > > your
> > > > > > > opinion on the matter.
> > > > > > > Currently all our transforms and actions are gathered under the
> > > > plugins
> > > > > > > section, this made sense when we started working on the project
> > but
> > > > > from
> > > > > > a
> > > > > > > user perspective this is confusing.
> > > > > > >
> > > > > > > The suggestion is to make at least 2 large categories to the
> > > > > > documentation
> > > > > > > being "Pipeline" and "Workflow" we can then move the
> > documentation
> > > > that
> > > > > > is
> > > > > > > located under "Hop Gui" or rewrite parts of this documentation
> > and
> > > do
> > > > > > cross
> > > > > > > references when needed.
> > > > > > >
> > > > > > > I think making these 2 large sections and adding the
> > > > transforms/actions
> > > > > > > here will greatly improve readability. We can still use the
> > plugins
> > > > > > section
> > > > > > > too, we can use it for external plugins or transforms/actions
> > that
> > > we
> > > > > > will
> > > > > > > not be adding to the default release in the future.
> > > > > > >
> > > > > > > Cheers,
> > > > > > > Hans
> > > > > > >
> > > > > >
> > > > >
> > > > >
> > > > > --
> > > > > Neo4j Chief Solutions Architect
> > > > > *✉ *matt.casters@neo4j.com
> > > > > ☎ +32486972937
> > > > >
> > > >
> > >
> >
>
Re: Documentation
Posted by Bart Maertens <ba...@know.bi>.
So the discussion is basically: do we include a Hop Gui top section or not?
In that case, the user manual more or less becomes the Hop Gui manual.
While we're at it, we could move the 'Tools' section to the
technical manual, where the Docker documentation currently is.
The technical guide needs some cleanup anyway: getting started is empty so
can be removed, the hop-uit docs can go as well.
The 'logo and icons' is definitely useful, but is a style guide rather than
purely technical documentation.
On Mon, Feb 22, 2021 at 8:33 AM Hans Van Akelyen <ha...@gmail.com>
wrote:
> Hi Bart,
>
> This is why I suggest removing the top level in your structure all
> together...
> 95% of what is written in the user manual is "Hop GUI" as you structure
> ends up with 4 levels the users will get lost.
> Most documentation I see in the field tries to keep it at 2 levels with 3
> levels being the exception. Users don't like to dig into sub levels (I know
> I don't).
> Imho everything there should be written from a gui perspective.
>
> If you go to what we have in the "pipeline" and "workflow" section now, it
> is just a placeholder for the links under it.
> That's why I added the let's add the general concept there and then on
> level 2 add all the "editor"/"config"/....
>
> A/B testing might be a path to follow, but then we need to gather more
> information than we do now and have to start analyzing it. I suggest this
> is something for the future. I do not think we have what it takes to add
> clickstream/reading info from our website at this point in time
>
> Cheers,
> Hans
>
>
> On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <ba...@know.bi>
> wrote:
>
> > Hop users will spend almost all of their time in Hop Gui, e.g. nobody
> will
> > create an action or transform outside of Hop Gui.
> > People will look for documentation where they will use and need it, not
> > where it makes most sense from a conceptual or technical point of view.
> >
> > Since the discussion is mostly around how we structure the left hand TOC
> > menu,we could do some A/B testing: refer to workflow, pipeline and other
> > docs from their own main sections in the ToC *and* from the Hop Gui
> > section.
> > If we measure which path users follow to get to a documentation page and
> > one turns out to be underused, we can phase it out.
> >
> >
> >
> > On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
> > hans.van.akelyen@gmail.com> wrote:
> >
> > > I also have a feeling the GUI topic is too broad and would contain
> > > everything making it useless...
> > > This is what happened now with the plugins section.
> > > I think we can also remove the GUI heading and just talk about concepts
> > and
> > > as a subtopic how they are handled in the GUI.
> > >
> > > - > Workflow (general concept)
> > > - - > Creating a workflow (GUI explanation)
> > > - - > Actions
> > > - - - > Action 1
> > > - - - > Action 2
> > > ....
> > >
> > >
> > >
> > >
> > > On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
> > > <ma...@neo4j.com.invalid> wrote:
> > >
> > > > I'm not sure I like the idea of putting everything and the kitchen
> sink
> > > > under "Hop GUI". Maybe we can flatten the tree a bit?
> > > > Perhaps we can have a number of top level entries like Workflows,
> > > > Pipelines, Metadata, Tools, ...?
> > > > We can put the password encryption plugin under the Hop Encr tool or
> > > under
> > > > a more generic "Security" heading. It's a non-trivial concern after
> > all.
> > > >
> > > > Cheers,
> > > > Matt
> > > >
> > > > On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <bart.maertens@know.bi
> >
> > > > wrote:
> > > >
> > > > > Hi Hans, All,
> > > > >
> > > > > I agree moving the plugin documentation out of the plugins category
> > is
> > > a
> > > > > necessity.
> > > > > Our initial structure was inspired by the Hop architecture, which
> > imho
> > > > is a
> > > > > way too technical perspective.
> > > > > The documentation structure should follow how people use Hop and
> > where
> > > > they
> > > > > would look for information.
> > > > >
> > > > > People will interact with transforms, actions, project & database
> > > config
> > > > > etc almost exclusively from Hop Gui.
> > > > > Therefore, my suggestion would be to use the 2 main 'Workflow' and
> > > > > 'Pipeline' sections you mentioned, but keep them in the Hop Gui
> > > section.
> > > > > Something like:
> > > > > - > Hop Gui
> > > > > - - > Workflows
> > > > > - - -> Workflow Editor
> > > > > - - - > Workflow Run Configurations
> > > > > - - - > Actions
> > > > > - - - > ....
> > > > > - - > Pipelines
> > > > > - - - > Pipeline Editor
> > > > > - - - > Pipeline Run Configurations
> > > > > - - - > Transforms
> > > > > - - - > ....
> > > > > - - > Testing
> > > > > - - > Projects & Environments
> > > > > - - > Metadata
> > > > > - - - > Databases
> > > > > - - > ....
> > > > >
> > > > > For the more configuration/administration oriented tasks, we could
> > add
> > > a
> > > > > Tools/Administration/Configuration section, something like:
> > > > > - > Tools (or Administration?)
> > > > > - - > Hop Conf
> > > > > - - > Hop Server
> > > > > - - > Hop Run
> > > > >
> > > > > I'm not sure where e.g. the password plugins would fit in, since
> > > they're
> > > > > not directly development or configuration related. We could keep
> > those
> > > in
> > > > > the current 'Plugins' section.
> > > > > - > Plugins
> > > > > - - > Password Plugins
> > > > >
> > > > > Regards,
> > > > > Bart
> > > > >
> > > > > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> > > > > hans.van.akelyen@gmail.com>
> > > > > wrote:
> > > > >
> > > > > > Hi Hoppers,
> > > > > >
> > > > > > I would like to restructure the documentation a bit and would
> love
> > > for
> > > > > your
> > > > > > opinion on the matter.
> > > > > > Currently all our transforms and actions are gathered under the
> > > plugins
> > > > > > section, this made sense when we started working on the project
> but
> > > > from
> > > > > a
> > > > > > user perspective this is confusing.
> > > > > >
> > > > > > The suggestion is to make at least 2 large categories to the
> > > > > documentation
> > > > > > being "Pipeline" and "Workflow" we can then move the
> documentation
> > > that
> > > > > is
> > > > > > located under "Hop Gui" or rewrite parts of this documentation
> and
> > do
> > > > > cross
> > > > > > references when needed.
> > > > > >
> > > > > > I think making these 2 large sections and adding the
> > > transforms/actions
> > > > > > here will greatly improve readability. We can still use the
> plugins
> > > > > section
> > > > > > too, we can use it for external plugins or transforms/actions
> that
> > we
> > > > > will
> > > > > > not be adding to the default release in the future.
> > > > > >
> > > > > > Cheers,
> > > > > > Hans
> > > > > >
> > > > >
> > > >
> > > >
> > > > --
> > > > Neo4j Chief Solutions Architect
> > > > *✉ *matt.casters@neo4j.com
> > > > ☎ +32486972937
> > > >
> > >
> >
>
Re: Documentation
Posted by Hans Van Akelyen <ha...@gmail.com>.
Hi Bart,
This is why I suggest removing the top level in your structure all
together...
95% of what is written in the user manual is "Hop GUI" as you structure
ends up with 4 levels the users will get lost.
Most documentation I see in the field tries to keep it at 2 levels with 3
levels being the exception. Users don't like to dig into sub levels (I know
I don't).
Imho everything there should be written from a gui perspective.
If you go to what we have in the "pipeline" and "workflow" section now, it
is just a placeholder for the links under it.
That's why I added the let's add the general concept there and then on
level 2 add all the "editor"/"config"/....
A/B testing might be a path to follow, but then we need to gather more
information than we do now and have to start analyzing it. I suggest this
is something for the future. I do not think we have what it takes to add
clickstream/reading info from our website at this point in time
Cheers,
Hans
On Mon, Feb 22, 2021 at 7:56 AM Bart Maertens <ba...@know.bi> wrote:
> Hop users will spend almost all of their time in Hop Gui, e.g. nobody will
> create an action or transform outside of Hop Gui.
> People will look for documentation where they will use and need it, not
> where it makes most sense from a conceptual or technical point of view.
>
> Since the discussion is mostly around how we structure the left hand TOC
> menu,we could do some A/B testing: refer to workflow, pipeline and other
> docs from their own main sections in the ToC *and* from the Hop Gui
> section.
> If we measure which path users follow to get to a documentation page and
> one turns out to be underused, we can phase it out.
>
>
>
> On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
> hans.van.akelyen@gmail.com> wrote:
>
> > I also have a feeling the GUI topic is too broad and would contain
> > everything making it useless...
> > This is what happened now with the plugins section.
> > I think we can also remove the GUI heading and just talk about concepts
> and
> > as a subtopic how they are handled in the GUI.
> >
> > - > Workflow (general concept)
> > - - > Creating a workflow (GUI explanation)
> > - - > Actions
> > - - - > Action 1
> > - - - > Action 2
> > ....
> >
> >
> >
> >
> > On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
> > <ma...@neo4j.com.invalid> wrote:
> >
> > > I'm not sure I like the idea of putting everything and the kitchen sink
> > > under "Hop GUI". Maybe we can flatten the tree a bit?
> > > Perhaps we can have a number of top level entries like Workflows,
> > > Pipelines, Metadata, Tools, ...?
> > > We can put the password encryption plugin under the Hop Encr tool or
> > under
> > > a more generic "Security" heading. It's a non-trivial concern after
> all.
> > >
> > > Cheers,
> > > Matt
> > >
> > > On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <ba...@know.bi>
> > > wrote:
> > >
> > > > Hi Hans, All,
> > > >
> > > > I agree moving the plugin documentation out of the plugins category
> is
> > a
> > > > necessity.
> > > > Our initial structure was inspired by the Hop architecture, which
> imho
> > > is a
> > > > way too technical perspective.
> > > > The documentation structure should follow how people use Hop and
> where
> > > they
> > > > would look for information.
> > > >
> > > > People will interact with transforms, actions, project & database
> > config
> > > > etc almost exclusively from Hop Gui.
> > > > Therefore, my suggestion would be to use the 2 main 'Workflow' and
> > > > 'Pipeline' sections you mentioned, but keep them in the Hop Gui
> > section.
> > > > Something like:
> > > > - > Hop Gui
> > > > - - > Workflows
> > > > - - -> Workflow Editor
> > > > - - - > Workflow Run Configurations
> > > > - - - > Actions
> > > > - - - > ....
> > > > - - > Pipelines
> > > > - - - > Pipeline Editor
> > > > - - - > Pipeline Run Configurations
> > > > - - - > Transforms
> > > > - - - > ....
> > > > - - > Testing
> > > > - - > Projects & Environments
> > > > - - > Metadata
> > > > - - - > Databases
> > > > - - > ....
> > > >
> > > > For the more configuration/administration oriented tasks, we could
> add
> > a
> > > > Tools/Administration/Configuration section, something like:
> > > > - > Tools (or Administration?)
> > > > - - > Hop Conf
> > > > - - > Hop Server
> > > > - - > Hop Run
> > > >
> > > > I'm not sure where e.g. the password plugins would fit in, since
> > they're
> > > > not directly development or configuration related. We could keep
> those
> > in
> > > > the current 'Plugins' section.
> > > > - > Plugins
> > > > - - > Password Plugins
> > > >
> > > > Regards,
> > > > Bart
> > > >
> > > > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> > > > hans.van.akelyen@gmail.com>
> > > > wrote:
> > > >
> > > > > Hi Hoppers,
> > > > >
> > > > > I would like to restructure the documentation a bit and would love
> > for
> > > > your
> > > > > opinion on the matter.
> > > > > Currently all our transforms and actions are gathered under the
> > plugins
> > > > > section, this made sense when we started working on the project but
> > > from
> > > > a
> > > > > user perspective this is confusing.
> > > > >
> > > > > The suggestion is to make at least 2 large categories to the
> > > > documentation
> > > > > being "Pipeline" and "Workflow" we can then move the documentation
> > that
> > > > is
> > > > > located under "Hop Gui" or rewrite parts of this documentation and
> do
> > > > cross
> > > > > references when needed.
> > > > >
> > > > > I think making these 2 large sections and adding the
> > transforms/actions
> > > > > here will greatly improve readability. We can still use the plugins
> > > > section
> > > > > too, we can use it for external plugins or transforms/actions that
> we
> > > > will
> > > > > not be adding to the default release in the future.
> > > > >
> > > > > Cheers,
> > > > > Hans
> > > > >
> > > >
> > >
> > >
> > > --
> > > Neo4j Chief Solutions Architect
> > > *✉ *matt.casters@neo4j.com
> > > ☎ +32486972937
> > >
> >
>
Re: Documentation
Posted by Bart Maertens <ba...@know.bi>.
Hop users will spend almost all of their time in Hop Gui, e.g. nobody will
create an action or transform outside of Hop Gui.
People will look for documentation where they will use and need it, not
where it makes most sense from a conceptual or technical point of view.
Since the discussion is mostly around how we structure the left hand TOC
menu,we could do some A/B testing: refer to workflow, pipeline and other
docs from their own main sections in the ToC *and* from the Hop Gui
section.
If we measure which path users follow to get to a documentation page and
one turns out to be underused, we can phase it out.
On Sun, Feb 21, 2021 at 11:42 PM Hans Van Akelyen <
hans.van.akelyen@gmail.com> wrote:
> I also have a feeling the GUI topic is too broad and would contain
> everything making it useless...
> This is what happened now with the plugins section.
> I think we can also remove the GUI heading and just talk about concepts and
> as a subtopic how they are handled in the GUI.
>
> - > Workflow (general concept)
> - - > Creating a workflow (GUI explanation)
> - - > Actions
> - - - > Action 1
> - - - > Action 2
> ....
>
>
>
>
> On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
> <ma...@neo4j.com.invalid> wrote:
>
> > I'm not sure I like the idea of putting everything and the kitchen sink
> > under "Hop GUI". Maybe we can flatten the tree a bit?
> > Perhaps we can have a number of top level entries like Workflows,
> > Pipelines, Metadata, Tools, ...?
> > We can put the password encryption plugin under the Hop Encr tool or
> under
> > a more generic "Security" heading. It's a non-trivial concern after all.
> >
> > Cheers,
> > Matt
> >
> > On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <ba...@know.bi>
> > wrote:
> >
> > > Hi Hans, All,
> > >
> > > I agree moving the plugin documentation out of the plugins category is
> a
> > > necessity.
> > > Our initial structure was inspired by the Hop architecture, which imho
> > is a
> > > way too technical perspective.
> > > The documentation structure should follow how people use Hop and where
> > they
> > > would look for information.
> > >
> > > People will interact with transforms, actions, project & database
> config
> > > etc almost exclusively from Hop Gui.
> > > Therefore, my suggestion would be to use the 2 main 'Workflow' and
> > > 'Pipeline' sections you mentioned, but keep them in the Hop Gui
> section.
> > > Something like:
> > > - > Hop Gui
> > > - - > Workflows
> > > - - -> Workflow Editor
> > > - - - > Workflow Run Configurations
> > > - - - > Actions
> > > - - - > ....
> > > - - > Pipelines
> > > - - - > Pipeline Editor
> > > - - - > Pipeline Run Configurations
> > > - - - > Transforms
> > > - - - > ....
> > > - - > Testing
> > > - - > Projects & Environments
> > > - - > Metadata
> > > - - - > Databases
> > > - - > ....
> > >
> > > For the more configuration/administration oriented tasks, we could add
> a
> > > Tools/Administration/Configuration section, something like:
> > > - > Tools (or Administration?)
> > > - - > Hop Conf
> > > - - > Hop Server
> > > - - > Hop Run
> > >
> > > I'm not sure where e.g. the password plugins would fit in, since
> they're
> > > not directly development or configuration related. We could keep those
> in
> > > the current 'Plugins' section.
> > > - > Plugins
> > > - - > Password Plugins
> > >
> > > Regards,
> > > Bart
> > >
> > > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> > > hans.van.akelyen@gmail.com>
> > > wrote:
> > >
> > > > Hi Hoppers,
> > > >
> > > > I would like to restructure the documentation a bit and would love
> for
> > > your
> > > > opinion on the matter.
> > > > Currently all our transforms and actions are gathered under the
> plugins
> > > > section, this made sense when we started working on the project but
> > from
> > > a
> > > > user perspective this is confusing.
> > > >
> > > > The suggestion is to make at least 2 large categories to the
> > > documentation
> > > > being "Pipeline" and "Workflow" we can then move the documentation
> that
> > > is
> > > > located under "Hop Gui" or rewrite parts of this documentation and do
> > > cross
> > > > references when needed.
> > > >
> > > > I think making these 2 large sections and adding the
> transforms/actions
> > > > here will greatly improve readability. We can still use the plugins
> > > section
> > > > too, we can use it for external plugins or transforms/actions that we
> > > will
> > > > not be adding to the default release in the future.
> > > >
> > > > Cheers,
> > > > Hans
> > > >
> > >
> >
> >
> > --
> > Neo4j Chief Solutions Architect
> > *✉ *matt.casters@neo4j.com
> > ☎ +32486972937
> >
>
Re: Documentation
Posted by Hans Van Akelyen <ha...@gmail.com>.
I also have a feeling the GUI topic is too broad and would contain
everything making it useless...
This is what happened now with the plugins section.
I think we can also remove the GUI heading and just talk about concepts and
as a subtopic how they are handled in the GUI.
- > Workflow (general concept)
- - > Creating a workflow (GUI explanation)
- - > Actions
- - - > Action 1
- - - > Action 2
....
On Sun, Feb 21, 2021 at 10:06 PM Matt Casters
<ma...@neo4j.com.invalid> wrote:
> I'm not sure I like the idea of putting everything and the kitchen sink
> under "Hop GUI". Maybe we can flatten the tree a bit?
> Perhaps we can have a number of top level entries like Workflows,
> Pipelines, Metadata, Tools, ...?
> We can put the password encryption plugin under the Hop Encr tool or under
> a more generic "Security" heading. It's a non-trivial concern after all.
>
> Cheers,
> Matt
>
> On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <ba...@know.bi>
> wrote:
>
> > Hi Hans, All,
> >
> > I agree moving the plugin documentation out of the plugins category is a
> > necessity.
> > Our initial structure was inspired by the Hop architecture, which imho
> is a
> > way too technical perspective.
> > The documentation structure should follow how people use Hop and where
> they
> > would look for information.
> >
> > People will interact with transforms, actions, project & database config
> > etc almost exclusively from Hop Gui.
> > Therefore, my suggestion would be to use the 2 main 'Workflow' and
> > 'Pipeline' sections you mentioned, but keep them in the Hop Gui section.
> > Something like:
> > - > Hop Gui
> > - - > Workflows
> > - - -> Workflow Editor
> > - - - > Workflow Run Configurations
> > - - - > Actions
> > - - - > ....
> > - - > Pipelines
> > - - - > Pipeline Editor
> > - - - > Pipeline Run Configurations
> > - - - > Transforms
> > - - - > ....
> > - - > Testing
> > - - > Projects & Environments
> > - - > Metadata
> > - - - > Databases
> > - - > ....
> >
> > For the more configuration/administration oriented tasks, we could add a
> > Tools/Administration/Configuration section, something like:
> > - > Tools (or Administration?)
> > - - > Hop Conf
> > - - > Hop Server
> > - - > Hop Run
> >
> > I'm not sure where e.g. the password plugins would fit in, since they're
> > not directly development or configuration related. We could keep those in
> > the current 'Plugins' section.
> > - > Plugins
> > - - > Password Plugins
> >
> > Regards,
> > Bart
> >
> > On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> > hans.van.akelyen@gmail.com>
> > wrote:
> >
> > > Hi Hoppers,
> > >
> > > I would like to restructure the documentation a bit and would love for
> > your
> > > opinion on the matter.
> > > Currently all our transforms and actions are gathered under the plugins
> > > section, this made sense when we started working on the project but
> from
> > a
> > > user perspective this is confusing.
> > >
> > > The suggestion is to make at least 2 large categories to the
> > documentation
> > > being "Pipeline" and "Workflow" we can then move the documentation that
> > is
> > > located under "Hop Gui" or rewrite parts of this documentation and do
> > cross
> > > references when needed.
> > >
> > > I think making these 2 large sections and adding the transforms/actions
> > > here will greatly improve readability. We can still use the plugins
> > section
> > > too, we can use it for external plugins or transforms/actions that we
> > will
> > > not be adding to the default release in the future.
> > >
> > > Cheers,
> > > Hans
> > >
> >
>
>
> --
> Neo4j Chief Solutions Architect
> *✉ *matt.casters@neo4j.com
> ☎ +32486972937
>
Re: Documentation
Posted by Matt Casters <ma...@neo4j.com.INVALID>.
I'm not sure I like the idea of putting everything and the kitchen sink
under "Hop GUI". Maybe we can flatten the tree a bit?
Perhaps we can have a number of top level entries like Workflows,
Pipelines, Metadata, Tools, ...?
We can put the password encryption plugin under the Hop Encr tool or under
a more generic "Security" heading. It's a non-trivial concern after all.
Cheers,
Matt
On Sun, Feb 21, 2021 at 1:03 PM Bart Maertens <ba...@know.bi> wrote:
> Hi Hans, All,
>
> I agree moving the plugin documentation out of the plugins category is a
> necessity.
> Our initial structure was inspired by the Hop architecture, which imho is a
> way too technical perspective.
> The documentation structure should follow how people use Hop and where they
> would look for information.
>
> People will interact with transforms, actions, project & database config
> etc almost exclusively from Hop Gui.
> Therefore, my suggestion would be to use the 2 main 'Workflow' and
> 'Pipeline' sections you mentioned, but keep them in the Hop Gui section.
> Something like:
> - > Hop Gui
> - - > Workflows
> - - -> Workflow Editor
> - - - > Workflow Run Configurations
> - - - > Actions
> - - - > ....
> - - > Pipelines
> - - - > Pipeline Editor
> - - - > Pipeline Run Configurations
> - - - > Transforms
> - - - > ....
> - - > Testing
> - - > Projects & Environments
> - - > Metadata
> - - - > Databases
> - - > ....
>
> For the more configuration/administration oriented tasks, we could add a
> Tools/Administration/Configuration section, something like:
> - > Tools (or Administration?)
> - - > Hop Conf
> - - > Hop Server
> - - > Hop Run
>
> I'm not sure where e.g. the password plugins would fit in, since they're
> not directly development or configuration related. We could keep those in
> the current 'Plugins' section.
> - > Plugins
> - - > Password Plugins
>
> Regards,
> Bart
>
> On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <
> hans.van.akelyen@gmail.com>
> wrote:
>
> > Hi Hoppers,
> >
> > I would like to restructure the documentation a bit and would love for
> your
> > opinion on the matter.
> > Currently all our transforms and actions are gathered under the plugins
> > section, this made sense when we started working on the project but from
> a
> > user perspective this is confusing.
> >
> > The suggestion is to make at least 2 large categories to the
> documentation
> > being "Pipeline" and "Workflow" we can then move the documentation that
> is
> > located under "Hop Gui" or rewrite parts of this documentation and do
> cross
> > references when needed.
> >
> > I think making these 2 large sections and adding the transforms/actions
> > here will greatly improve readability. We can still use the plugins
> section
> > too, we can use it for external plugins or transforms/actions that we
> will
> > not be adding to the default release in the future.
> >
> > Cheers,
> > Hans
> >
>
--
Neo4j Chief Solutions Architect
*✉ *matt.casters@neo4j.com
☎ +32486972937
Re: Documentation
Posted by Bart Maertens <ba...@know.bi>.
Hi Hans, All,
I agree moving the plugin documentation out of the plugins category is a
necessity.
Our initial structure was inspired by the Hop architecture, which imho is a
way too technical perspective.
The documentation structure should follow how people use Hop and where they
would look for information.
People will interact with transforms, actions, project & database config
etc almost exclusively from Hop Gui.
Therefore, my suggestion would be to use the 2 main 'Workflow' and
'Pipeline' sections you mentioned, but keep them in the Hop Gui section.
Something like:
- > Hop Gui
- - > Workflows
- - -> Workflow Editor
- - - > Workflow Run Configurations
- - - > Actions
- - - > ....
- - > Pipelines
- - - > Pipeline Editor
- - - > Pipeline Run Configurations
- - - > Transforms
- - - > ....
- - > Testing
- - > Projects & Environments
- - > Metadata
- - - > Databases
- - > ....
For the more configuration/administration oriented tasks, we could add a
Tools/Administration/Configuration section, something like:
- > Tools (or Administration?)
- - > Hop Conf
- - > Hop Server
- - > Hop Run
I'm not sure where e.g. the password plugins would fit in, since they're
not directly development or configuration related. We could keep those in
the current 'Plugins' section.
- > Plugins
- - > Password Plugins
Regards,
Bart
On Sun, Feb 21, 2021 at 9:46 AM Hans Van Akelyen <ha...@gmail.com>
wrote:
> Hi Hoppers,
>
> I would like to restructure the documentation a bit and would love for your
> opinion on the matter.
> Currently all our transforms and actions are gathered under the plugins
> section, this made sense when we started working on the project but from a
> user perspective this is confusing.
>
> The suggestion is to make at least 2 large categories to the documentation
> being "Pipeline" and "Workflow" we can then move the documentation that is
> located under "Hop Gui" or rewrite parts of this documentation and do cross
> references when needed.
>
> I think making these 2 large sections and adding the transforms/actions
> here will greatly improve readability. We can still use the plugins section
> too, we can use it for external plugins or transforms/actions that we will
> not be adding to the default release in the future.
>
> Cheers,
> Hans
>