Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update user documentation structure #414

Merged
merged 33 commits into from
Feb 23, 2022
Merged

Update user documentation structure #414

merged 33 commits into from
Feb 23, 2022

Conversation

thebe14
Copy link
Contributor

@thebe14 thebe14 commented Feb 18, 2022

Summary

The documentation needs some changes to the structure, in order to accommodate new services and to make it easier to navigate. A lot of (most) content from the EGI-ACE D2.3 and D2.5 should end up in our user documentation.

  • Added the necessary new pages
  • Provided content for the new pages
  • Revised content of existing pages to bring them in line with the rest of the documentation style.

Related issue : Implements #411

@thebe14
Added content to new pages
8b54bc5 
Revised content on existing pages to have an unifirm style across the user documentation
@thebe14
Integrated content distribution under Compute
20bc212
@andrea-manzi
Copy link
Contributor

i see one problem now...the links to the doc we have added to the D2.5 deliverables will be incorrect ..so we should revise them ASAP when we approve this PR

@andrea-manzi
Copy link
Contributor

great work! let's make the linter happy and then we can have a preview and review the changes

gwarf
gwarf reviewed Feb 18, 2022
View reviewed changes
Copy link
Member

@gwarf gwarf left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks.
Added a few comments, mainly letting other service owners review the content for their services.
Once it lints well we can enable the preview.

content/en/users/aai/_index.md Outdated Show resolved Hide resolved
content/en/users/aai/check-in/_index.md Outdated Show resolved Hide resolved
content/en/users/compute/orchestration/im/_index.md Outdated Show resolved Hide resolved
@thebe14
Copy link
Contributor Author

thebe14 commented Feb 18, 2022

i see one problem now...the links to the doc we have added to the D2.5 deliverables will be incorrect ..so we should revise them ASAP when we approve this PR

EGI-ACE D2.5 updated

@thebe14
Copy link
Contributor Author

thebe14 commented Feb 18, 2022

@enolfc @gwarf ready for preview

@thebe14 thebe14 mentioned this pull request Feb 18, 2022
Open
@andrea-manzi andrea-manzi added the safe for preview Pull request vetted as safe for preview label Feb 19, 2022
@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

@gwarf
Copy link
Member

gwarf commented Feb 19, 2022 •
edited
Loading

Looks good!
Some quick/first feedback: I'm not sure at all about https://docs.egi.eu/documentation/414/users/getting-started/task-force/ like about how it's named, where it's in the menu.
The FedCloud Task Force is only a very specific task force, focusing on mainly the cloud activities. I would find this better in the Compute part, or otherwise in something named/organised differently.
Same for the CLI in the getting started, it would look like it's a CLI for all EGI services, while it's certainly not the case

@thebe14
Copy link
Contributor Author

thebe14 commented Feb 19, 2022 •
edited
Loading

I'm not sure at all about https://docs.egi.eu/documentation/414/users/getting-started/task-force/ like about how it's named, where it's in the menu. The FedCloud Task Force is only a very specific task force, focusing on mainly the cloud activities. I would find this better in the Compute part, or otherwise in something named/organised differently.

I agree. That will get improved when the Getting Started part gets revised next. A lot of stuff about how to request access, the architecture, and more from D2.3 and D2.5 need to be added. But it is not what this PR should fix.

Same for the CLI in the getting started, it would like it's a CLI for all EGI services, while it's certainly not the case

The CLI page starts with this text, that I think is enough to not leave the impression that this is the CLI that can handle anything:

"The various public EGI services can be managed and used/accessed with a wide variety of command-line interface (CLI) tools. The documentation of each service contains a summary of the CLIs that can be used with that service, together with recommendations on which one to use in what context."

FedCloud CLI is more or less "the CLI" for EGI, a lot of docs pages refer to it (there were many places that were introducing fedcloudcli, now all those refer to /users/getting-started/cli). The docs for services that need additional CLIs will mention them. And fedcloudcli is being improved to cover more and more of the services. Finally, improving this is not the purpose of this PR.

@thebe14
Copy link
Contributor Author

thebe14 commented Feb 19, 2022

@andrea-manzi I did a lot of changes in the top pages for the data services. uniformized titles and subtitles (e.g. no links or acronyms in titles), added a What is it? paragraph to each. please review them, let me know if it's good (or you can improve it further in future PRs).

Data TODOs:

  • the openRDM page has to be filled in
  • some diagrams from D2.5 could also make their way into the docs

@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

@andrea-manzi
Copy link
Contributor

we should remove draft: true from the openRDM page

@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

@thebe14
Made rucio page public
7e823cb 
CHanged linktitles for data management services
@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

@thebe14
renamed linktitle for Rucio
50c8c04 
As the servive is to be renamed too
@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

1 similar comment
@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

@enolfc
Copy link
Contributor

enolfc commented Feb 22, 2022

I agree. That will get improved when the Getting Started part gets revised next. A lot of stuff about how to request access, the architecture, and more from D2.3 and D2.5 need to be added. But it is not what this PR should fix.

Should we just remove the taskforce page in this PR? It's not bringing any value right now and I fear we will be postponing moving it forever. It simply does not belong to the docs.egi.eu but it's more a TCB-like activity and should be documented as such in confluence

@thebe14
Copy link
Contributor Author

thebe14 commented Feb 22, 2022

Should we just remove the taskforce page in this PR? It's not bringing any value right now and I fear we will be postponing moving it forever.

Added draft flag, removed links to it.

@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

andrea-manzi
andrea-manzi approved these changes Feb 22, 2022
View reviewed changes
Copy link
Contributor

@andrea-manzi andrea-manzi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work, let's go for it

@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/414

enolfc
enolfc approved these changes Feb 23, 2022
View reviewed changes
Copy link
Contributor

@enolfc enolfc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Thanks @thebe14

@gwarf gwarf merged commit b1d1423 into EGI-Federation:main Feb 23, 2022
This was referenced Feb 23, 2022
Merged
Merged
Merged
Closed
@gwarf gwarf mentioned this pull request Mar 7, 2022
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@gwarf gwarf gwarf left review comments

@andrea-manzi andrea-manzi andrea-manzi approved these changes

@enolfc enolfc enolfc approved these changes

@vardizzo-lab vardizzo-lab Awaiting requested review from vardizzo-lab vardizzo-lab is a code owner

@CatalinCondurache CatalinCondurache Awaiting requested review from CatalinCondurache

@glarocca glarocca Awaiting requested review from glarocca glarocca is a code owner

Assignees
No one assigned
Labels
safe for preview Pull request vetted as safe for preview
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@thebe14 @andrea-manzi @gwarf @enolfc