Netplan: Create a "one true path" Netplan tutorial

[rkratky]

Background

Netplan is the main network-configuration framework used by Ubuntu. While its documentation covers a lot of ground, there are always things to improve. One of those things is the absence of a real tutorial (as defined by Diatáxis. The docs site for Netplan offers a bunch of topics under the Tutorial heading, but they don't really fit the bill for a tutorial.

Task

• (If needed) Become familiar with the way Diatáxis understands and describes tutorials:
  • Diatáxis: Tutorials
  • The idea of a tutorial
• Consider the existing docs (Netplan: Tutorial) and draft a "real" tutorial for Netplan; this can be both written from scratch as well as based on existing content.

This is not a simple undertaking, but it should also not be viewed with too much respect. It's perfectly fine to divide this issue into more than one sub-goal. For example, one could first sketch a skeleton (a bullet list of things that need to be in the tutorial) and then start filling in the gaps (either developing new content, or reusing existing).

[ade555]

Hi, @rkratky. I'm interested in taking up this issue. I already have an idea of what Diataxis considers a tutorial, and I think I can come up with something worthwhile.

However, if I am to update all the topics under the tutorial section, is there a certain folder structure you would prefer me to use?

[rkratky]

I already have an idea of what Diataxis considers a tutorial, and I think I can come up with something worthwhile.

:+1: Great. Don't hesitate to reach out if you have any questions.

if I am to update all the topics under the tutorial section, is there a certain folder structure you would prefer me to use?

Good point. Right now, the Netplan repo doesn't use any subdirectories (under the doc/ directory), which could get confusing soon. While not strictly necessary, I'd suggest moving away from the flat structure to using subdirectories for each content type (i.e. explanation/, howto/, reference/, tutorial/).

If you decide to go this way, then I think it would be useful to have a separate PR just for the hierarchy change (no content updates, just putting the docs files into their respective new directories and updating the paths where needed, so that the docs site builds successfully).

[ade555]

Hi, @rkratky . Thank you for your response. I think it's better practice to have the files in their directories, so I'll make the PR before updating the content for the tutorials.

I'll try to make the first PR in about a week. Does that sound good?

[rkratky]

This has been fixed in https://github.com/canonical/netplan/pull/458