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 <[email protected]> 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 <[email protected]> > 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 < >> [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 >> > > > > >> > > > >> > > >> > >> >
