Implement _data/terms.yml for more cohesive Documentation

[bnvk]

As a new user of any software project, a frustrating experience I encounter is stale documentation and lack of cohesive terminology as these factors lead to more challenging (than it could be) and sometimes show-stoping confusion.

Luckily, with Qubes, I have not been completely stumped by anything, yet, but I still would like to help improve the documentation for less technically inclined users.

Example 1

While configuring my Qubes to to have a TorVM via this documentation the page references the TemplateVM fedora-20-x64 which is outdated as a fresh install creates TemplateVM called fedora-21

Example 2

Additionally, throughout the docs the referencing of the different type of VMs changes quite a bit. For example, on the TorVM page, the following references to TemplateVM are used:

template
template vm
templateVM

These are all tiny & easy mistakes to make as a human writing natural language documentation. Thus, I propose adding variables to a file like _data/terms.yml so that in the docs, the writer would type {{terms.vm_template}} or {{terms.vm_template_name}} which Jekyll would render as TemplateVM and fedora-21 respectively, upon building the site.

I think this change will help by keeping things current and more cohesive. I'm happy to do this tedious task if it is welcomed (and will be accepted) as it will help me get more familiar with Qubes and contribute back to the community!

[andrewdavidwong]

While configuring my Qubes to to have a TorVM via this documentation the page references the TemplateVM fedora-20-x64 which is outdated as a fresh install creates TemplateVM called fedora-21

I don't think it's accurate to call this "outdated." The latest stable version of Qubes is R2, which installs fedora-20-x64 templates by default. Version R3.0-rc1 is a release candidate, which is "considered unstable and not ready for production." I think the official documentation should apply to the latest stable release, since this is what most users will (and should) be using.

Additionally, throughout the docs the referencing of the different type of VMs changes quite a bit. For example, on the TorVM page, the following references to TemplateVM are used: [...]

I understand where you're coming from, and I can certainly see the merits of having a _data/terms.yml. However, here are some counterpoints:

1. It's somewhat uncharitable to refer to all of these kinds of variations in language as "mistakes." I agree, of course, that template vm and templateVM are simply sloppy. However, referring to a TemplateVM as a "template" can be a proper and reasonable stylistic variation which avoids awkwardness. (It's also strictly accurate: a TemplateVM is literally a type of template.) If it's clear to the reader that the word "template" refers to a TemplateVM, then calling it a "template" in some instances might simply make for more readable documentation (as opposed to documentation which sounds like it was written by a robot).
2. More importantly, however, it is crucially important that all the user documentation be easily readable in the original Markdown source. This is, in fact, one of the main reasons we've migrated to the current system for managing qubes-doc. So, anything which hinders plain text source readability must provide a very substantial benefit in order to justify the cost it imposes. A text littered with variables like {{terms.vm_template}} or {{terms.vm_template_name}} is much more difficult to read (but, granted, still readable). This is not to say that we should never use such variables in our source, but we must be very careful to maintain plain text readability for users of all technical levels.

[andrewdavidwong]

While configuring my Qubes to to have a TorVM via this documentation the page references the TemplateVM fedora-20-x64 which is outdated as a fresh install creates TemplateVM called fedora-21

I don't think it's accurate to call this "outdated." The latest stable version of Qubes is R2, which installs fedora-20-x64 templates by default. Version R3.0-rc1 is a release candidate, which is "considered unstable and not ready for production." I think the official documentation should apply to the latest stable release, since this is what most users will (and should) be using.

Additionally, throughout the docs the referencing of the different type of VMs changes quite a bit. For example, on the TorVM page, the following references to TemplateVM are used: [...]

I understand where you're coming from, and I can certainly see the merits of having a _data/terms.yml. However, here are some counterpoints:

1. It's somewhat uncharitable to refer to all of these kinds of variations in language as "mistakes." I agree, of course, that template vm and templateVM are simply sloppy. However, referring to a TemplateVM as a "template" can be a proper and reasonable stylistic variation which avoids awkwardness. (It's also strictly accurate: a TemplateVM is literally a type of template.) If it's clear to the reader that the word "template" refers to a TemplateVM, then calling it a "template" in some instances might simply make for more readable documentation (as opposed to documentation which sounds like it was written by a robot).
2. More importantly, however, it is crucially important that all the user documentation be easily readable in the original Markdown source. This is, in fact, one of the main reasons we've migrated to the current system for managing qubes-doc. So, anything which hinders plain text source readability must provide a very substantial benefit in order to justify the cost it imposes. A text littered with variables like {{terms.vm_template}} or {{terms.vm_template_name}} is much more difficult to read (but, granted, still readable). This is not to say that we should never use such variables in our source, but we must be very careful to maintain plain text readability for users of all technical levels.

[bnvk]

@axon-qubes ah, sorry that was my bad. I didn't realize I was using an officially unreleased version of Qubes (R3.0-rc1), which I am. I agree "documentation should apply to the latest stable release"

I see the point you make about using template and TemplateVM and i'm all for making things friendly to read and less robot sounding (nothing against the robots) out there ;)

Definitely, would be super important to make the variable names short and easy to understand and not have too many of them. Hrm. Perhaps the TemplateVM might be a bit too far, but the case of names of distros, etc... would minimize the amount of {{ ... }} in the text.

As per the "version" issue. Have you given any thought to versioning the documentation? That might be a case where the variables come in real handy.

[bnvk]

@axon-qubes ah, sorry that was my bad. I didn't realize I was using an officially unreleased version of Qubes (R3.0-rc1), which I am. I agree "documentation should apply to the latest stable release"

I see the point you make about using template and TemplateVM and i'm all for making things friendly to read and less robot sounding (nothing against the robots) out there ;)

Definitely, would be super important to make the variable names short and easy to understand and not have too many of them. Hrm. Perhaps the TemplateVM might be a bit too far, but the case of names of distros, etc... would minimize the amount of {{ ... }} in the text.

As per the "version" issue. Have you given any thought to versioning the documentation? That might be a case where the variables come in real handy.

[andrewdavidwong]

@bnvk

Perhaps the TemplateVM might be a bit too far, but the case of names of distros, etc... would minimize the amount of {{ ... }} in the text.

Sounds reasonable to me.

As per the "version" issue. Have you given any thought to versioning the documentation? That might be a case where the variables come in real handy.

I can imagine some kind of versioning scheme being useful. Do you have one in mind? One concern is that some parts of the documentation remain accurate across Qubes versions, while others do not.

[andrewdavidwong]

@bnvk

Perhaps the TemplateVM might be a bit too far, but the case of names of distros, etc... would minimize the amount of {{ ... }} in the text.

Sounds reasonable to me.

As per the "version" issue. Have you given any thought to versioning the documentation? That might be a case where the variables come in real handy.

I can imagine some kind of versioning scheme being useful. Do you have one in mind? One concern is that some parts of the documentation remain accurate across Qubes versions, while others do not.

[bnvk]

@axon-qubes as per Fedora 23 becoming the default installed version with 3.1, it might be time to revisit this issue?

[bnvk]

@axon-qubes as per Fedora 23 becoming the default installed version with 3.1, it might be time to revisit this issue?

[andrewdavidwong]

Yes, I think it's a good idea for any term we know will change regularly in the future (e.g., fedora-x).

[andrewdavidwong]

Yes, I think it's a good idea for any term we know will change regularly in the future (e.g., fedora-x).