You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@hop.apache.org by Hans Van Akelyen <ha...@gmail.com> on 2021/03/10 20:42:36 UTC
Re: Documentation
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>.
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