simplify WSL tutorial #224
Conversation
- remove steps that are probably not necessary (e.g., checking systemd
from PowerShell)
- reduces complexity in web app (e.g., no CSS)
- provides an example of what VSCode offers (e.g., snippets)
- shortens section on interoperability (e.g., focus on terminal-based
moving of image from Windows)
- increase emphasis on built-in tooling at the start
- favour terminal commands over GUI where appropriate (e.g., Windows
terminal keybinding, instead of chevron)
- avoid confusing naming ("UbuntuWSL" is not a helpful name for the web
project)
- various small fixes and adjustments
There was a problem hiding this comment.
Hi, @edibotopic. This is great! I genuinely like how you were able to cut out the fluff and help the reader focus on the necessary aspects of the tutorial.
I left some comments already, but there are a few extra you might want to look into:
- Since you changed the web example, some of the images no longer align and need to be changed
- Some of the text formatting seems a bit off, particularly the notes. Perhaps it's a convention I'm unaware of
I think that's about it for now. Great work!
| @@ -32,6 +41,8 @@ This command will enable the features necessary to run WSL and also install the | |||
|
|
|||
| WSL supports a variety of Ubuntu releases. Check our [reference on the distributions](https://documentation.ubuntu.com/wsl/en/latest/reference/distributions/) for more information. | |||
|
|
|||
| At any one time, multiple instances of Ubuntu on WSL can be installed on the same machine. | |||
There was a problem hiding this comment.
Reading this section sounded a bit awkward to me. Can we update it to something like this"
"WSL supports multiple Ubuntu releases, and you can install several Ubuntu instances on your machine at the same time. For more information about available distributions, see our reference guide."
| ``` | ||
|
|
||
| You should see the content of your HTML file displayed on the terminal. | ||
| ### Browse your Ubuntu files graphically in Windows Explorer |
There was a problem hiding this comment.
In this section, I think we should still try to reference the index.html created in the previous section. For example, we can ask the reader to type explorer.exe to specifically open up the webTest directory so they can confirm the creation of their file. Then we can let them know that it's possible to run the command at any time.
My thinking is that after creating the index.html file, the reader will need some guidance to specifically find it in the explorer.
| To exit the server, type `ctrl + c` from within the Ubuntu terminal. | ||
| You can edit the HTML file to see the changes in real-time. With the server | ||
| still running, open a second instance of the same Ubuntu distro. In that second | ||
| instance, edit the text in `index.html`, save the file and refresh the browser |
There was a problem hiding this comment.
I think we can update this to:
"In that second instance, edit the text in index.html, by typing “nano index.html” and editing the text."
This gives provision for readers who have still not grasped the whole nano business, especially because we mentioned nano only once previously.
| Navigate to the `Extensions` menu in the sidebar and search for `Remote Development`. | ||
|
|
||
| This is an extension pack that allows you to open any folder in a container, remote machine, or in WSL. Alternatively, you can just install `Remote - WSL` via the terminal. | ||
| Open VSCode, navigate to the `Extensions` menu in the sidebar and find the `Remote Development` from MicroSoft. |
There was a problem hiding this comment.
Minor typo.
Fix:
Open VSCode, navigate to the Extensions menu in the sidebar, and find the Remote Development extension from Microsoft
|
|
||
| We'll use Visual Studio Code to modify the `index.html` file we created earlier. To get started, confirm that you're in the right directory with this command: | ||
| In Ubuntu, make sure you are in `webTest` by printing the working directory: |
There was a problem hiding this comment.
I previously added an example output for the pwd command so the reader can have some sort of reference on what to expect. Is there a reason you removed it? Perhaps I overlooked something.
|
|
||
| ### Create a systemd service to run your web page | ||
| ### Create a systemd service to server your web page |
There was a problem hiding this comment.
Minor typo:
server -> serve
| @@ -401,7 +387,7 @@ If you don't see `systemd`, it means `systemd` is not enabled. Follow these step | |||
| WantedBy=multi-user.target | |||
| ``` | |||
|
|
|||
| In the snippet above, replace `yourUsername` with your actual username. All the code is doing is to tell `systemd` to navigate to the `ubuntuWSL` folder and run `python3 -m http.server` on port 3000, whenever you open a WSL instance. | |||
| Port 3000 is specified here so as not to block the default 8000 port. | |||
There was a problem hiding this comment.
I've had experiences where readers copy code snippets and expect them to work right out of the box without making modifications. This mostly happens with beginners, but I think it's a good idea to nudge them to make necessary changes:
We specify port 3000 so as not to block the default 8000 port. Ensure you include your username in the workingDirectcory and user fields. Type ctrl + s to save and ctrl + x to exit the editor.
|
|
||
| ```text | ||
| $ sudo nano /etc/systemd/system/python-http-server.service | ||
| $ sudo nano /etc/systemd/system/py-server.service |
There was a problem hiding this comment.
The service name here is py-server.service, but everywhere else, it is referenced as python-http-server.service
Closes #201
Continues work started by @ade555 to improve the WSL tutorial.
Main changes:
UDENG-6579