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.

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

docs: streamline tutorials, add and update how-to guides #860

Merged
merged 13 commits into from
Aug 13, 2024

Conversation

edibotopic
Copy link
Collaborator

@edibotopic edibotopic commented Aug 7, 2024

UDENG-3595

This PR makes several significant changes to the structure and content of the UP4W tutorial and the how-to sections of the docs.

The tutorial has been greatly simplified and shortened to focus on installation, adding a Pro token and verifying Pro attachment. There are now an increased number of short how-to guides that aim to be brief and reliable sets of instructions for specific tasks.

Tabbed interfaces are used when presenting alternate configuration options.

Major changes:

  • Decoupling of UP4W and Landscape: installation and automatic Pro-attachment with UP4W does not depend on Landscape. The Getting Started tutorial now only covers the process of installing UP4W, configuring Pro and verifying Pro attachment. The tutorial should now be easier to navigate successfully for a first-time user interested in automatic Pro-attachment of Ubuntu WSL instances. This decoupling is also reflected in the how-to guides, which now treat adding a Pro token and configuring Landscape as independent tasks.
  • Simplification of installation how-to guide: the original how-to guide on installation and configuration consisted of several dropdown menus, callout blocks and caveats, making it quite difficult to follow for a task that should be straightforward. It has been simplified, in part by presenting a tabbed interface with the two primary options for installing with Windows registry and installing with the graphical Windows application.
  • Extraction of short how-to guides from tutorial content: another reason for the length of the original tutorial was the inclusion of sections relating to backing up instances and uninstalling applications. These have been extracted into self-contained how-to guides as they contain useful information that a user is likely to return to for a variety of reasons in the context of Ubuntu WSL in general. They are referenced in the tutorial but are not fully included to avoid breaking up the flow of the tutorial.
  • Updated guidelines on Landscape config: the Landscape integration with UP4W has undergone some changes, particularly with respect to the UI. The documentation now reflects these changes.
  • Increased elaboration of Windows registry option: using the Windows registry is an important option for enterprise users. It is now given increased prominence in the documentation with some additional text explaining why it is useful and images for user instruction. The getting started tutorial uses the graphical application for installation but the default tab in the how-to guides is for the Windows registry.

Minor changes:

  • UI improvements: use of tabbed interfaces for user choice between Windows app and Windows registry
  • Internal references: updated internal Sphinx references for many sections
  • Rewording/fixes: minor changes throughout
  • Updated images: throughout

UDENG-3595

@edibotopic edibotopic marked this pull request as ready for review August 7, 2024 10:50
@edibotopic edibotopic requested a review from a team as a code owner August 7, 2024 10:50
Copy link
Contributor

@jibel jibel left a comment

Choose a reason for hiding this comment

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

Very good. I noticed one typo.

docs/howto/backup-and-restore.md Outdated Show resolved Hide resolved
Copy link
Contributor

@CarlosNihelton CarlosNihelton left a comment

Choose a reason for hiding this comment

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

I like very much the proposed structure, just have few minor items to bring into consideration.

docs/howto/assets/registry-child-window.png Outdated Show resolved Hide resolved
docs/howto/backup-and-restore.md Outdated Show resolved Hide resolved
docs/howto/reuse-me Outdated Show resolved Hide resolved
docs/howto/set-up-landscape-client.md Outdated Show resolved Hide resolved
docs/howto/set-up-landscape-client.md Outdated Show resolved Hide resolved
docs/howto/set-up-up4w.md Outdated Show resolved Hide resolved
docs/howto/set-up-up4w.md Outdated Show resolved Hide resolved
Copy link
Contributor

@CarlosNihelton CarlosNihelton left a comment

Choose a reason for hiding this comment

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

Very good!

@edibotopic edibotopic requested a review from jibel August 13, 2024 07:19
Copy link
Contributor

@jibel jibel left a comment

Choose a reason for hiding this comment

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

Looks good to me. Thanks for this update!

@edibotopic
Copy link
Collaborator Author

Thanks both -- I will mark the remaining conversations as "resolved" now.

@edibotopic edibotopic merged commit 070a9f3 into main Aug 13, 2024
2 checks passed
@edibotopic edibotopic deleted the docs-rework-howtos branch August 13, 2024 08:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants