document relationship of TemplateVM's and TemplateBasedVM's (home) folder(s)

[adrelanos]

Current situation:
The /home folder of a TemplateVM is copied to a TemplateBasedVM at creation time of the TemplateBasedVM. From then, TemplateBasedVM's /home folder is left untouched.

(Source: https://groups.google.com/forum/#!topic/qubes-users/WwVJhGA-Xnc)

Current documentation (?):
https://www.qubes-os.org/en/doc/template-implementation/

Issue:
The current documentation does not explain this well. Likely because it's more targeting developers rather than users.

[adrelanos]

Here is a documentation addition that I suggest. However, I am not good it's well understandable to new users. Wiser words welcome.

Introduction

The /home folder of a TemplateVM is copied to a TemplateBasedVM at creation time of the TemplateBasedVM. From then, TemplateBasedVM's /home folder is left untouched.

Changes in /home, /usr/local and /rw/config persist, which means, files stored there will still be available after restarting the TemplateBasedVM. All changes to other folders do not persist. If you would like to make persistent changes to other folders, you must do them in the TemplateVM.

[adrelanos]

Here is a documentation addition that I suggest. However, I am not good it's well understandable to new users. Wiser words welcome.

Introduction

The /home folder of a TemplateVM is copied to a TemplateBasedVM at creation time of the TemplateBasedVM. From then, TemplateBasedVM's /home folder is left untouched.

Changes in /home, /usr/local and /rw/config persist, which means, files stored there will still be available after restarting the TemplateBasedVM. All changes to other folders do not persist. If you would like to make persistent changes to other folders, you must do them in the TemplateVM.

[andrewdavidwong]

Current documentation (?):
https://www.qubes-os.org/en/doc/template-implementation/

Issue:
The current documentation does not explain this well. Likely because it's more targeting developers rather than users.

That page is in the developers' documentation, so it's correct that it targets developers rather than users. (It's about template implementation, not just templates per se.)

The users' page on templates is here: https://www.qubes-os.org/en/doc/templates/

In light of this, do you still want to see your change implemented? If so, on which page? Both?

[andrewdavidwong]

Current documentation (?):
https://www.qubes-os.org/en/doc/template-implementation/

Issue:
The current documentation does not explain this well. Likely because it's more targeting developers rather than users.

That page is in the developers' documentation, so it's correct that it targets developers rather than users. (It's about template implementation, not just templates per se.)

The users' page on templates is here: https://www.qubes-os.org/en/doc/templates/

In light of this, do you still want to see your change implemented? If so, on which page? Both?

[adrelanos]

Yes, I want my change implemented. Where would be a good place to add it? I don't know. I just feel this is a missing bit of information.

[adrelanos]

Yes, I want my change implemented. Where would be a good place to add it? I don't know. I just feel this is a missing bit of information.

[andrewdavidwong]

What do you think of this, @adrelanos?

[andrewdavidwong]

What do you think of this, @adrelanos?

[adrelanos]

The text sounds nice. But I was hoping to make this information available to users.

[adrelanos]

The text sounds nice. But I was hoping to make this information available to users.

[adrelanos]

Maybe https://www.qubes-os.org/en/doc/getting-started/ would be an appropriate place?

[adrelanos]

Maybe https://www.qubes-os.org/en/doc/getting-started/ would be an appropriate place?

[andrewdavidwong]

The text sounds nice. But I was hoping to make this information available to users.

Well, that's why I asked which page(s) you wanted to add it to. :)

Maybe https://www.qubes-os.org/en/doc/getting-started/ would be an appropriate place?

It strikes me as too specific to go on Getting Started, but I could be wrong. My thought is that it would be odd to tell users about very specific quirks of the filesystem relationship on a page which is designed just to "get them started." Do you think this is information they need just to get started with Qubes?

If the concern is that they need this information in order not to make costly security mistakes or otherwise shoot themselves in the foot, then that sounds like what the Security Guidelines page is attempting to do.

[andrewdavidwong]

The text sounds nice. But I was hoping to make this information available to users.

Well, that's why I asked which page(s) you wanted to add it to. :)

Maybe https://www.qubes-os.org/en/doc/getting-started/ would be an appropriate place?

It strikes me as too specific to go on Getting Started, but I could be wrong. My thought is that it would be odd to tell users about very specific quirks of the filesystem relationship on a page which is designed just to "get them started." Do you think this is information they need just to get started with Qubes?

If the concern is that they need this information in order not to make costly security mistakes or otherwise shoot themselves in the foot, then that sounds like what the Security Guidelines page is attempting to do.

[andrewdavidwong]

Now that I think about it, it would make sense also to add this information to the Templates page and the Security Guidelines page. In general, we want to make sure that important information is repeated in all relevant places throughout the documentation, since the documentation is typically used as a reference guide (which means that users tend to read different sections, out of order, depending on their own particular needs and interests at the time, and are therefore likely to miss an important piece of information if it's mentioned in only one place).

[andrewdavidwong]

Now that I think about it, it would make sense also to add this information to the Templates page and the Security Guidelines page. In general, we want to make sure that important information is repeated in all relevant places throughout the documentation, since the documentation is typically used as a reference guide (which means that users tend to read different sections, out of order, depending on their own particular needs and interests at the time, and are therefore likely to miss an important piece of information if it's mentioned in only one place).

[adrelanos]

Probably too much for getting started.

You can put it https://www.qubes-os.org/en/doc/security-guidelines/ if
no one else has a better suggestion. I don't.

It's just something that sometimes comes up and I would be able to just
answer by providing a link to it.

Do you have documentation templates? I.e. can you write such modules
[documentation text snippets] and then import them were you want them?

[adrelanos]

Probably too much for getting started.

You can put it https://www.qubes-os.org/en/doc/security-guidelines/ if
no one else has a better suggestion. I don't.

It's just something that sometimes comes up and I would be able to just
answer by providing a link to it.

Do you have documentation templates? I.e. can you write such modules
[documentation text snippets] and then import them were you want them?

[andrewdavidwong]

Do you have documentation templates? I.e. can you write such modules [documentation text snippets] and then import them were you want them?

Sorry, I don't understand. Can you rephrase?

[andrewdavidwong]

Do you have documentation templates? I.e. can you write such modules [documentation text snippets] and then import them were you want them?

Sorry, I don't understand. Can you rephrase?

[adrelanos]

Axon:

Do you have documentation templates? I.e. can you write such modules [documentation text snippets] and then import them were you want them?

Sorry, I don't understand. Can you rephrase?

You create a file template_something.

Then in page get_started and security_page you just do
import:template_something. Then the text from template_something will be
load and inserted into get_started and security_page. Therefore no
duplication of text. You can change the text in one place and it will be
updated in all places. That's "templates", but not "raw images", but
"textual templates".

[adrelanos]

Axon:

Do you have documentation templates? I.e. can you write such modules [documentation text snippets] and then import them were you want them?

Sorry, I don't understand. Can you rephrase?

You create a file template_something.

Then in page get_started and security_page you just do
import:template_something. Then the text from template_something will be
load and inserted into get_started and security_page. Therefore no
duplication of text. You can change the text in one place and it will be
updated in all places. That's "templates", but not "raw images", but
"textual templates".

[andrewdavidwong]

You create a file template_something.
[...]

Oh, I see. No, we don't do anything like that because one of our goals is to have the raw Markdown source as easily human-readable as possible.

[andrewdavidwong]

You create a file template_something.
[...]

Oh, I see. No, we don't do anything like that because one of our goals is to have the raw Markdown source as easily human-readable as possible.

[andrewdavidwong]

What do you think about this and this, @adrelanos?

[andrewdavidwong]

What do you think about this and this, @adrelanos?

[adrelanos]

Nice!

[adrelanos]

Nice!