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