Whonix vs Qubes Docs

Development
1

Continuing the discussion from [Todo] Wiki page regarding Qubes Filesystem Persistence:

Sorry to rehash what seems to have been an active and passionate discussion (issue 1201). Maybe I’m reading into it what I want to read, but it seems that the consensus opinion was to port “clear, short instructions on how to make Whonix work within Qubes!” I would agree that that’s the correct approach on both sides.

Barring a complete integration of Whonix into Qubes, both sites should maintain their respective docs, including some overlap when it comes to general concepts, setup procedures, and basic troubleshooting. The cost to maintaining basic docs is minimal, and these pages are reviewed frequently by many users.

The overlap is necessary because users may approach each of the projects from diverse backgrounds and not have the motivation to explore the other project in much depth, if at all. This is especially (maybe only ideally?) true for Whonix users. Qubes tends to have more technically-savvy users [judging by each vocal community which is obviously a biased measure since Whonix users value their privacy by default], which makes sense since you have to have some grasp of technical concepts to appreciate a secure OS. On the other hand, there is no technical prerequisite for wanting greater privacy. Information about Qubes needs to be presented in an even more approachable fashion to Whonix users. ie custom Qubes Getting Started page on Whonix.org…

Each project should host on its own, documentation regarding advanced, niche, project specific information. Advanced users are more likely to seek out documentation from other sources. More importantly, the documentation needs to reside where it will be best maintained. When necessary, pages should be mirrored or linked instead of keeping multiple versions.

One thing that stands out from the discussion is the need for specific criteria to determine where pages should be hosted. Otherwise, docs can develop a tendency to be over-ambitious and balloon with obsolete or poorly maintained information.

Some possible criteria:

  1. Which user-base is more likely to actively maintain topic?
  2. Does topic represent basic functionality? Then, keep in both places.
  3. Does topic represent optional, advanced, specific, or experimental usage? Then leave with specific project.

Examples to show that it’s not so clear cut and every page needs to be decided case-by-case:

Using Whonix as Disposable VM: Very clearly laid out already by the generalized DispVM instructions on qubes site. But not hard to maintain in both places. Is this basic functionality or optional? I don’t know. When Whonix users ask how to do this, will a link to the qubes site be sufficient or will they need more specific instructions? Ideal solution is to have automated Whonix DispVM setup when Whonix is installed… (In that sense, if it’s something that should be installed by default, maybe it is basic usage.)

Tor Bridges: With the notable exception of Chinese & Iranian users, this should not be considered basic functionality. There is also no doubt that this page would be better maintained by the Whonix user-base. Bridges are an integral part of Tor, which makes it indirectly a part of Whonix. There is no obvious relation to Qubes. Bridges stay here. (With respect to users needing censorship circumvention, it also seems more likely for them to come to Whonix before Qubes).

Qubes Filesystem Persistence: This is an advanced concept general to the Qubes OS as a whole. The code may receive patches and documenting changes faithfully is well within the interest of the qubes team. Main article should be on qubes-os.org. What happens when Whonix user wants to customize appVM and can’t figure out why changes keep getting reset? Whonix wiki should link to the main article and present a stub with Whonix-specific information.

my 2 cents…

@adw

2 Likes
2

In #1202 the argument by @mfc was that the Whonix bridges documentation should be moved to the Qubes website, so that it can be included in the Qubes offline docs.

There is also no doubt that this page would be better maintained by the Whonix user-base.

Yes.

Bridges are an integral part of Tor, which makes it indirectly a part of Whonix. There
is no obvious relation to Qubes. Bridges stay here.

.

(With respect to
users needing censorship circumvention, it also seems more likely for
them to come to Whonix before Qubes).

So far true, but…

… While the sponsorship does not entitle this task directly, the goal is to make censorship circumvention easier for Qubes users.

3

Good day,

Well, calling this a quite hard decision to make would be an understatement, at least in my eyes, seeing how both sides offer quite a few significant arguments which shouldn’t simply be brushed aside when making said choice.

However, what I can’t understand is why overlap seems to be such an emotional topic, seemingly for the sole reason of simplicity. Like @entr0py has shown, some users will always find Whonix first. Adding to that the fact that even though it looks rather overblown, the current documentation has its size for a reason. I’m the first to argue for simplicity, however when it comes to anonymity, cutting corners can (and has) cost quite a lot. Seeing how what they have proposed to put in their quick start guide would solely focus on the setup of Whonix, users can easily shoot their legs.

Now, you may very reasonably say that for setup, all this information isn’t required. However that train of thought neglects basic safety precautions and forgets that failing once is enough to in the worst case expose you or at least turn you pseudonymous. So as long as there are no plans to include information on what anonymity is and how it is achieved, I feel like it can’t be supported in good conscious. You may of course reasonably disagree with this.

Adding to that the fact that once streamlining both the homepage and documentation are done (sadly good alternatives for mediawiki which don’t use an abundance of scripting are rather scares) in theory having both coexist both online and offline may be more reasonable than it might appear now and we have something to carefully discuss.

Have a nice day,

Ego

1 Like
4

Don’t understand how that argument supports movement of any docs. Given that Whonix software is bundled with Qubes (and not required to be integrated completely), can’t they likewise simply bundle Whonix’s offline docs with Qubes offline docs? Formatting issues? Quality issues? Licensing?

5

Good day,

Looking at that discussion, I think the main point is like you’ve guessed our current design.

Quote:

The Whonix site & docs are poorly organized & designed- a user currently has to scroll 2+ full browser windows to find a bunch of columns and then visually parse “Primary Guides → Install → Binary Install Guide” to get to any actionable steps and (even on that page) it is disorienting and requires a full scroll to get to any useful information.

Source: depreciate torvm, add Whonix templates (at minimum whonix-gw) to Qubes installer · Issue #1201 · QubesOS/qubes-issues · GitHub

That’s why I mentioned that:

As when the Whonix documentation is more readable it could simply be combined with what the Qubes team plans and coexist, at least from my point of view.

Have a nice day,

Ego

1 Like
6

There is no Whonix offline documentation. It is an unsolved issue.

https://forums.whonix.org/t/offline-documentation-discussion

That is the problem.

Also, “move” for bridges would mean “duplicate”. Since Non-Qubes-Whonix users still need these docs. And duplication is awful. Changes will be made in one but not the other, so merging gets difficult.

Rather than making all of Whonix’s documentation accessible in offline documentation, it would be simpler to do that just with a single page. (That will need manual fixes to make ti readable, but much more doable for 1 page than the whole wiki.)

Yes, if the Whonix mediawiki offline documentation can be sorted out.

Or, I was also wondering… In case we port (might be considered in future, but really no strong plan for now) Whonix documentation from mediawiki to jekyll, then it would be simple to add more, most or even all of Whonix documentation to Qubes jekyll based website. The Whonix documentation would be just have a few unique pages such as Whonix homepage, Whonix documentation, Whonix help and such. Probably not so simple to due links. And non-perfect.

The Qubes documentation would, I am sure, demand to leave aside “if you are using Qubes-Whonix” and “if you are using Non-Qubes-Whonix”.

Short discussion on jekyll:
splitting Whonix documentation into a short and long edition for better usability - #11 by Ego

7

Since one of those links (in the original quoted post) is to my comment on GitHub, I just want to point out that I was quoting someone else’s comment (as you can see for yourself) because that comment was more appropriate to the current issue instead of the other issue. (In other words, it was purely to keep the conversations on GitHub organized, not an endorsement of the view being expressed) I have never asked Patrick (or anyone) to move any documentation from an external site to to the Qubes website or documentation. (In fact, I have often suggested that it would be fine to leave documentation on external sites and link to it from the Qubes website.)

For me, this isn’t an emotional topic. My own view is pretty simple: Each project should be free to maintain its own documentation however it likes. (I have nothing against Whonix’s documentation. I think it’s great, and I’ve personally found it very useful. In fact, I think we have a lot to learn from it in writing and designing the Qubes documentation.) If the two projects want to coordinate or combine their documentation to some degree (for the sake of deduplication or otherwise), that’s great. But if the terms of such an arrangement aren’t acceptable to one of the parties, then that party has every right to decline.

3 Likes
8

Good day,

Just looked through the most famous static site generators there are, including Jekyll. Non of them offer any big advantage over creating sites manually with html because the time saved on the base is lost when considering the removal of all the scripts it uses. However, translation over prose.io seems to soely be possible with Jekyll for some reason so that needs to be considered and is the reason why I’ll still have to change to it.

For the wiki portion though, as it is hard to really create a well made documentation solution by hand, I’d propose changing from Mediawiki, which has problems with translations and the offline mode to DokuWiki which after having tested through all the more famous wiki solutions seems to be best suited for us.

It doesn’t rely on JS, is easy to translate and doesn’t use complex databases but rather plain text files which can be easily exported and used to base an offline documentation on it. Adding to that, they seem to have a few ways to integrate it with existing solutions, including Jekyll, which in turn would mean that both the homepage, download site, etc. and the wiki have a similar look, making the whole user experience far better. However, having it seperatly would be possible as well. Here is a link to their project, having tried it, I can tell you that setup is definetly easier than with mediawiki: https://www.dokuwiki.org

Have a nice day,

Ego