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