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 <[email protected]> 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 <[email protected]> > 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 < > > [email protected]> 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 > > > <[email protected]> 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 <[email protected] > > > > > > 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 < > > > > > [email protected]> > > > > > 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 > > > > *✉ *[email protected] > > > > ☎ +32486972937 > > > > > > > > > >
