Improvement suggestions for documentation

[poautran]

In GitLab by @MarieSpi on Nov 7, 2024, 13:37 GMT+1:

Main page: https://ewoksweb.readthedocs.io/en/latest/index.html
{width=1112 height=486}

ewoksweb 1.0

ewoksweb is a frontend to create, visualize and execute ewoks workflows in the web.

… export a JSON file. It is a dynamic and easy way to create a JSON workflow.

ewoksweb has been developed by the Software group of the European Synchrotron.

The documentation is inspired by the diataxis approach.

Useful information here? Could it be places at the end just as an information?

It could be interesting to add a section named: "About ewoksweb".

Homogeneity with (Use Ewoks graphical interfaces — ewoks 0.5.0 documentation – cf. img bellow)

{width=468 height=209}

Install locally

Install the ewoksweb Python package

pip install ewoksweb

Start the application via

ewoksweb

For beginner: Command line to use in a terminal or any code editor/integrated development environment (vscode, jupyter…). Should it be interesting to inform that it is python related and you should have python installed?

The web app will be available at localhost:8000.

Should we precise this link? http://127.0.0.1:8000/edit

Note

ewoksweb takes the port 8000 by default. If there are other applications running on this port (e.g. iTunes radio on Mac), another port can be chosen

ewoksweb --port 6660

Also by default, ewoksweb will save ewoks resources (workflows, tasks, icons) in the current folder. This can be changed through the --dir command line argument

ewoksweb --dir /path/to/ewoksserver/resources

This note could be simplified or is it relevant for this page?

Tutorials

Follow the learning-oriented tutorials that will help accomplish a sequence of steps in order to:

• Create your first Workflow
• Create your first task

Replace those lines by boxes like the following example from ewoks documentation (https://ewoks.esrf.fr/en/latest/tasks/index.html)

{width=329 height=97}

Example of grid from ewoks doc : (https://ewoks.esrf.fr/en/latest/tasks/index.html)

How-to guides

The how-to guides are descriptions targeting the following tasks:

• New-Open-Save workflows
• Execute workflows
• Monitoring executed workflows

Explanations

General useful information regarding:

• Editor basic structure
• Embedded Nodes in ewoksweb
• Rules for link validation
• Node editing
• Link editing

To me all this misses some illustrations to help beginner/user to understand what is what and what is for what (usage).

Documentation of related projects:

• ewokscore : create workflows and implement tasks
• ewoksorange : create and execute workflows with a desktop GUI
• ewoksppf : execute cyclic workflows
• ewoksdask : parallelize workflow execution
• ewoksjob: distribute workflow execution
• ewoksserver: REST server to manage and execute workflows
• ewoksutils : developer utilities

I feel that it could be better to have a link to go to the general documentation (ewokpr) instead of random Projects (or I misunderstood?)

Next propositions for the next pages of ReadTheDoc for ewoksweb documentation in the next comments

Migrated from GitLab: https://gitlab.esrf.fr/workflow/ewoks/ewoksweb/-/issues/278

[poautran]

In GitLab by @MarieSpi on Nov 7, 2024, 13:58 GMT+1:

{width=468 height=206}

Create your first Workflow
(https://ewoksweb.readthedocs.io/en/latest/tutorials/create_your_first_workflow.html)

By following the steps in this tutorial, you will be able to create a basic workflow.

New Workflow

When landing in ewoksweb you can start building your workflow immediately. The editor has in the middle of the top bar the title Untitled workflow (unsaved) that will be replaced by the name of the workflow once the workflow is first saved.

When mouse pass over the word "ewoks" of the previous text, ddd a blurb or a tooltip to remind what is ewoksweb shortly. This idea could be extended on a lot of thematic words.

Add nodes

On the left side the sidebar of tasks can be used to add nodes in your workflow. The tasks exist in their categories that can be opened by clicking on them.

1. Click on the General category that exists by default.
2. Drag-and-Drop a taskSkeleton task in the canvas in the middle of the page twice.
3. After dropping your tasks two nodes appear with the label taskSkeleton that can be re-arranged by dragging them on the canvas.

Add a link

Nodes can be connected with links that can be created in two ways:

1. By clicking on the handles that the nodes have on their sides and sliding without releasing the click to a handle of another node.
2. By clicking on a handle and then on another handle.

Save a Workflow

In order to save the workflow on the server:

1. Click on the button with the disk at the right of the top bar.
2. On the appearing dialog with the title Give the new workflow identifier give a name for your workflow.
3. Click SAVE WORKFLOW
4. If the name you provided is not unique an error message will appear at the bottom-left Workflow ‘theName’ already exists. In this case give another name and try again.

Add illustrations to get it more didactic and attractive.
We could refer to, or get inspire from ewoks documentation (https://ewoks.readthedocs.io/en/latest/howtoguides/gui.html) and/or eowksfordevs (https://ewoksfordevs.readthedocs.io/en/stable/#/).

{width=468 height=208}

[poautran]

In GitLab by @MarieSpi on Nov 7, 2024, 14:07 GMT+1:

{width=468 height=205}

Create your first task (https://ewoksweb.readthedocs.io/en/latest/tutorials/create_a_task.html)

Tasks can be managed in the second tab of the upper drawer. By clicking on the dropdown the tasks in their categories are revealed with their assigned icons. When clicking on a task underneath it buttons appear for deleting, editing and cloning the task. By deleting the task it is removed from the server permanently and can affect the workflows that contain it if any.

A beginner should understand what and where is: second tab? upper drawer? dropdown? assigned icons? And what about this paragraph? where is the task underneath it buttons appear for deleting, editing and cloning the task? Is the last sentence usefull?
Need to reformulate and illustrate?

Editing and cloning opens a dialog with all task properties below also described in Ewokscore:

• New Name - Identifier: the Task will be saved to file with this name-identifier.

Tool tip to replace the comment after ":"?

• Task Type
• Category
• Optional Inputs
• Required Inputs
• Outputs
• Icon which is the icon that will appear in the task and in the nodes that will be created from this task.
  Tasks can be discovered in the server if the slider Task Discovery is used. When is set it open an input where the module name will be inserted and a button to start the discovery process on the server. The process assumes that the absolute path to the python module is given for the discovery mechanism to find the python tasks described in there.

In general, I do not get the utility of this section "Create your first task" and what is it adding to the previous "Create your first workflow". We could be more interested in how to fill inputs and outputs of each nodes and links for a workflow, which I can not really find neither here nore in the "Node editing" (https://ewoksweb.readthedocs.io/en/latest/explanations/node_editing.html) or "Link editing" (https://ewoksweb.readthedocs.io/en/latest/explanations/link_editing.html) parts of ewoksweb ReadTheDoc documentation.

[poautran]

In GitLab by @MarieSpi on Nov 7, 2024, 15:01 GMT+1:

{width=1079 height=341}
In the ewoks documentation > Tutorial > Create workflow > ewoksweb (https://ewoks.esrf.fr/en/latest/tutorials/create_workflow.html)

We could Add the documentation of ewoks to reach the ReadTheDoc ewoksweb documentation (https://ewoksweb.readthedocs.io/en/latest/index.html) and maybe, the HowTo and Tutorials (https://gitlab.esrf.fr/workflow/ewokstutorials/ewoksfordevs or https://ewoksfordevs.readthedocs.io/en/stable/#/).

[poautran]

In GitLab by @loichuder on Nov 7, 2024, 15:39 GMT+1:

Thanks for the analysis. You can go ahead and apply some of the easy fixes you found.

I agree that the "Create you first task" page is not useful: it can be removed.