Netplan docs rework #333

daniloegea · 2023-03-07T14:57:00Z

Description

I tried to follow the ideas from diataxis.fr and adapted parts of our documentation to the framework.

Tutorial: I created a tutorial to guide the user that has very little knowledge about Netplan through a number of tasks they can execute in a virtual machine. Each task increments the previous one and introduce more things one can do with Netplan.
- Should I introduce netplan status as well? I didn't use it because it's only available in Lunar at the moment...
How-tos: I changed the sets of examples to look more like how-tos. I removed or simplified some of the explanations to go straight to the point of the problem we are trying to solve. I also added a few more how-tos to the document. The indentation was normalized to 2 spaces.
Reference: I added a new initial section to the document that shows the general structure of a Netplan YAML file and changed the examples so they will be complete configuration files and the reader can easily see where each settings fits in the configuration.

Checklist

Runs make check successfully.
Retains 100% code coverage (make check-coverage).
New/changed keys in YAML format are documented.
(Optional) Adds example YAML for new feature.
(Optional) Closes an open bug in Launchpad.

Also, decrese the YAML files indentation and add few more howtos.

Add one initial section describing the general structure of a Netplan YAML file. Improve the examples so the reader can see where a given setting fits in the configuration.

slyon

This is not yet a full review, but I had an initial look and left some inline comments.

I'd like to ask some real Diataxis expert like @tmihoc to do a full review.

The docs can be built and rendered locally from Danilo's branch, using cd doc/ && make install && make run

doc/tutorials.md

doc/netplan-yaml.md

doc/examples.md

doc/netplan-tutorial.md

slyon · 2023-03-08T10:17:55Z

doc/netplan-tutorial.md

+Now create a virtual machine called `netplan-lab0`:
+
+```bash
+lxc init --vm ubuntu:22.04 netplan-lab0


I wonder if we should use something newer here, like ubuntu-daily:devel to make the latest Netplan features (like "status" CLI) available.

hmm I don't know, I think the focus should be stable releases, those are the ones users will install after all. We can update it to ubuntu:23.04 in a couple of months I guess. For now I think I will mention netplan status is only available in netplan 0.106.

I agree. And your suggestion wfm.

Once backported to Jammy, we can even drop it back to ubuntu:22.04 as using a LTS release in the tutorial sounds like a good idea.

doc/netplan-tutorial.md

Also, link the new netplan-tutorial.md in the main page index.

Now the tutorial and how-tos sections will show up in the sidebar menu.

By linking the main file in the front page the reader will be sent directly to the text instead of a page with only an index.

Sphinx was logging many warnings like "WARNING: Document headings start at H2, not H1"

Also, add a new section about bonds to the tutorial.

slyon

Thank you, this is looking nice! +1 from my side, but let's wait for Teodora's comments before merging this.

Just a few more small suggestions/nitpicks inline.

doc/netplan-tutorial.md

doc/netplan-yaml.md

doc/examples.md

slyon · 2023-03-09T10:50:04Z

doc/examples.md

 ```

-To instead set a static IP address, use the addresses key, which takes a list of (IPv4 or IPv6), addresses along with the subnet prefix length (e.g. /24). DNS information can be provided as well, and the gateway can be defined via a default route:
+# How to configure a static IP address on an interface


suggestion: I feel like we should remove the "How to " prefix here and on all the other instances below. They're all listed under the "How-to guides" sections after all. DRY.

Suggested change

# How to configure a static IP address on an interface

# Configure a static IP address on an interface

As they are listed one after another the "How to" gets very repetitive... I followed the naming conventions from here though https://diataxis.fr/how-to-guides/#pay-attention-to-naming

Okay. Let's wait and see how Teodora thinks about it!

About the "How to" bit in titles: Daniele said we should use it inside the docs but not in the navigation table. I.e., in this case,

inside the doc: "How to configure a static IP address on an interface"

in the navigation table: "Configure a static IP address on an interface"

Also, move nm-devices to the end of the list in the reference document as they are not supposed to be used in a normal scenario.

doc/netplan-tutorial.md

tmihoc · 2023-03-13T09:14:02Z

doc/netplan-tutorial.md

+    try       Try to apply a new netplan config to running system, with automatic rollback
+```
+
+As you can see, netplan has a number of sub commands. Let's explore some of them.


The sections that follow are nicely done but I'm not sure they fit with Daniele's idea of a tutorial. To use a culinary metaphor, the tutorial should be about helping the user bake that first cake, not about giving the user an introduction to the ingredients, utensils, and basic procedures -- no matter how gentle that introduction may be, that is work that should be done in the Ref / How-to docs.

tmihoc · 2023-03-13T09:24:22Z

doc/netplan-tutorial.md

+This file was automatically generated by `cloud-init` when the system was initialized. As noted in the comments, changes to this file will not persist.
+
+# Enabling your second network interface with DHCP
+


This section is excellent -- as a How-to guide.

tmihoc · 2023-03-13T09:26:44Z

doc/netplan-tutorial.md

+```
+
+Use the command `cat` to see its content:
+


Depending on your audience, you might want to clarify that this is a Unix command. Maybe not necessary in this particular case but, as a rule of thumb, always try to help the user understand which pieces are a part of your product and which one are not.

tmihoc · 2023-03-13T09:34:12Z

doc/netplan-tutorial.md

+```
+
+In the output, the MAC address is the number in front of the `link/ether` property.
+```


So, here, 1000? Always clarify. PS: This seems wrong. In the YAML below I see that the macaddress is 00:16:..., so I probably interpreted "the number in front of the link/ether property" wrong. That could be because I don't really know much about this. But, is there any chance someone else will make the same mistake? Either way, it's better to avoid unclear descriptions.

tmihoc · 2023-03-13T09:41:06Z

doc/netplan-yaml.md

+  > `nm-devices` are used in situations where Netplan doesn't support the connection type. The raw configuration expected by NetworkManager can be defined and will be passed as is (passthrough) to the `.nmconnection` file. Users will not normally use this type of device.
+
+All the properties for all the device types will be described in the next sections.
+


Would it be possible / make sense to follow the structure in this doc https://juju.is/docs/sdk/metadata-yaml ?, where each top-level key gets its own section, which clarifies the status, purpose, and structure of the key, and also gives examples, e.g., https://juju.is/docs/sdk/metadata-yaml#heading--assumes ?

We need to take care, as the same markdown file is also used to build our man pages (e.g. https://manpages.ubuntu.com/manpages/kinetic/man5/netplan.5.html) and the HTML documentation shipped in /usr/share/doc/netplan/netplan.html. And we need to make sure it is being rendered properly everywhere.

tmihoc · 2023-03-13T10:32:28Z

Hi! I think these are all great improvements, and I would publish them right away, using any comments to plan future work.

The comments amount to the following recommendations:

In general: Help the user distinguish visually between main content and tangents (i.e., set off notes that give links to further information, or notes with caveats about edge-cases, etc.).
In general: Help the user distinguish between content that pertains to your product and other types of content (e.g., netplan commands vs. lxc commands vs. general Unix commands etc.)
In general (though especially in the Tutorial / How-to guides): Avoid making the user look back, ahead, or sideways (try to stick to "below" and nothing else).
In a Tutorial / How-to guide, always keep the user in active mode. E.g., Use verbal (doc and) section titles ("Do x", not "Doing x"), where each title should be a step in the bigger story of the Tutorial / How-to guide.
Distinguish between Tutorial and How-to guides / Reference docs. To use a culinary metaphor, even if it will inevitably involve mention of ingredients / utensils (Reference material), and procedures (How-to material), the Tutorial must always stay focused on baking the cake.
In Reference docs: (a) Add a doc for every Netplan command. (b) For docs focused on giving the spec of a yaml file, structure the doc around the top-level keys.

Happy to clarify further.

daniloegea · 2023-03-13T19:07:08Z

I really appreciate the thorough review you provided, @tmihoc

We'll try to adopt all your suggestions in our documentation!

slyon · 2023-03-14T10:45:36Z

Thank you very much @tmihoc and @daniloegea for your input!

I marked the "little things" that Danilo already fixed as "resolved" and will merge the PR as-is. We'll then work on a follow-up PR to fix the bigger things separately.

Adding man pages for all the commands. Improving the network types descriptions a little. Follow-up for #333 COMMITS: * docs: add missing manpages Add manpages for the commands "info", "ip", "rebind" and "status". * docs: improve the Netplan reference The list of network keys are indexing their respective sections. Each section was expanded with a short description and explanation about the network type with a small example. * doc: refine wording & formatting

I tried to follow the ideas from diataxis.fr and adapted parts of our documentation to the framework. * Tutorial: I created a tutorial to guide the user that has very little knowledge about Netplan through a number of tasks they can execute in a virtual machine. Each task increments the previous one and introduce more things one can do with Netplan. * How-tos: I changed the sets of examples to look more like how-tos. I removed or simplified some of the explanations to go straight to the point of the problem we are trying to solve. I also added a few more how-tos to the document. The indentation was normalized to 2 spaces. * Reference: I added a new initial section to the document that shows the general structure of a Netplan YAML file and changed the examples so they will be complete configuration files and the reader can easily see where each settings fits in the configuration. COMMITS: * docs: Add a "getting started" netplan tutorial * docs: Make the examples look more like howtos Also, decrese the YAML files indentation and add few more howtos. * docs: Add more details to the reference manual Add one initial section describing the general structure of a Netplan YAML file. Improve the examples so the reader can see where a given setting fits in the configuration. * docs: remove old tutorials.md file Also, link the new netplan-tutorial.md in the main page index. * docs: fix man page rendering * docs: improve the new sections visualization Now the tutorial and how-tos sections will show up in the sidebar menu. * docs: use netplan status in the tutorial * docs: link the main howtos file in the main page By linking the main file in the front page the reader will be sent directly to the text instead of a page with only an index. * docs: fix formating and typos * docs: fix some warning from Sphinx Sphinx was logging many warnings like "WARNING: Document headings start at H2, not H1" * docs: Improve examples for consistency Also, add a new section about bonds to the tutorial. * docs: fix typos and formatting Also, move nm-devices to the end of the list in the reference document as they are not supposed to be used in a normal scenario. * docs: minor adjustments to the text

Adding man pages for all the commands. Improving the network types descriptions a little. Follow-up for #333 COMMITS: * docs: add missing manpages Add manpages for the commands "info", "ip", "rebind" and "status". * docs: improve the Netplan reference The list of network keys are indexing their respective sections. Each section was expanded with a short description and explanation about the network type with a small example. * doc: refine wording & formatting

Danilo Egea Gondolfo added 3 commits March 6, 2023 16:36

docs: Add a "getting started" netplan tutorial

0b3feba

docs: Make the examples look more like howtos

7e99c10

Also, decrese the YAML files indentation and add few more howtos.

docs: Add more details to the reference manual

beb5796

Add one initial section describing the general structure of a Netplan YAML file. Improve the examples so the reader can see where a given setting fits in the configuration.

slyon reviewed Mar 8, 2023

View reviewed changes

Danilo Egea Gondolfo added 8 commits March 8, 2023 11:42

docs: remove old tutorials.md file

1e1b3f7

Also, link the new netplan-tutorial.md in the main page index.

docs: fix man page rendering

0388db1

docs: improve the new sections visualization

eaa8a6a

Now the tutorial and how-tos sections will show up in the sidebar menu.

docs: use netplan status in the tutorial

11c1d06

docs: link the main howtos file in the main page

f06381b

By linking the main file in the front page the reader will be sent directly to the text instead of a page with only an index.

docs: fix formating and typos

011c843

docs: fix some warning from Sphinx

d08dfec

Sphinx was logging many warnings like "WARNING: Document headings start at H2, not H1"

docs: Improve examples for consistency

01761d8

Also, add a new section about bonds to the tutorial.

daniloegea force-pushed the netplan_docs_rework branch from 35b8015 to 01761d8 Compare March 8, 2023 17:44

slyon approved these changes Mar 9, 2023

View reviewed changes

docs: fix typos and formatting

f6043d5

Also, move nm-devices to the end of the list in the reference document as they are not supposed to be used in a normal scenario.

tmihoc reviewed Mar 13, 2023

View reviewed changes

tmihoc approved these changes Mar 13, 2023

View reviewed changes

docs: minor adjustments to the text

79af7de

daniloegea force-pushed the netplan_docs_rework branch from 3c9fbd0 to 79af7de Compare March 13, 2023 19:00

slyon merged commit 51fee38 into canonical:main Mar 14, 2023

slyon mentioned this pull request Apr 3, 2023

Netplan docs rework (Part 2) #337

Merged

5 tasks

	# How to configure a static IP address on an interface
	# Configure a static IP address on an interface

		This file was automatically generated by `cloud-init` when the system was initialized. As noted in the comments, changes to this file will not persist.

		# Enabling your second network interface with DHCP

		> `nm-devices` are used in situations where Netplan doesn't support the connection type. The raw configuration expected by NetworkManager can be defined and will be passed as is (passthrough) to the `.nmconnection` file. Users will not normally use this type of device.

		All the properties for all the device types will be described in the next sections.

Netplan docs rework #333

Netplan docs rework #333

Uh oh!

Conversation

daniloegea commented Mar 7, 2023 • edited by slyon Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

slyon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

slyon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tmihoc Mar 13, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tmihoc commented Mar 13, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

daniloegea commented Mar 13, 2023

Uh oh!

slyon commented Mar 14, 2023

Uh oh!

Uh oh!

daniloegea commented Mar 7, 2023 •

edited by slyon

Loading

tmihoc Mar 13, 2023 •

edited

Loading

tmihoc commented Mar 13, 2023 •

edited

Loading