New website for the community (based on qubes-os.org)

[deeplow]

Hi there!

With the moving of all unofficial docs onto the Qubes-Community organization, there will be the need to have a website to host them. My proposal is to fork the qubes-os.org website and make all the required changes to make sure it cannot be confused by users with the official website.

Proof of Concept

I've got a demo example of this here: https://deeplow.github.io (for proof of concept purposes only - the code changes need to be redone)

Some of the stuff implemented:

• left only the "external documentation"
• created new categories for documentation
• replaced default "blue qubes" color with a greenish for clear visual distinction from qubes-os.org
• added very visible link to the official qubes website (top-right corner)
• remade footer
• added Qubes Communiy README to homepage

This didn't didn't take much time to do, trashing this idea. It's just that this migration will be way easier than anything else I can think of. Plus @awokd I'm volunteering to make the necessary changes (as you can see by the PoC)

Advantages

• website is already made and looks pretty nice 🙂 (also, low development / migration "cost")
• integration with github for contributing to docs already exists ("edit this page" links)
• user familiarity
• workflow / update scripts already developed
• smooth migration of the docs onto it's "new house"

Potential Problems

Confusion with Official Website

I think this is something that has potential to happen whatever the website design is. But in this case the fact the forked website would look visually similar we'd have to make sure we clearly signal that it's not the official website.

In my proof of concept I've signaled this by:

• replacing the default "blue qubes" color with a greenish for clear visual distinction from qubes-os.org
• added very visible link to the official qubes website (top-right corner)
• added link to qubes-os.org on footer
• replaced the "Q" logo with "qubes community"

But other ideas on how to make this distiction even more clear are

Licensing

Something else that we'll need is the agreement of the qubes team. Since this has potential to have dissenting opinions and utimately it's up to them since ITL owns the codebase.

The website doesn't have a license, meaning that we can't technically fork
it until it has one @andrewdavidwong (or we can have explicit permission by the qubes team)

[andrewdavidwong]

replacing the default "blue qubes" color with a greenish for clear visual distinction from qubes-os.org

This might not have any effect for colorblind users or users on text-based or other types of web browsers.

added very visible link to the official qubes website (top-right corner)
added link to qubes-os.org on footer
replaced the "Q" logo with "qubes community"

These changes are good, but some might view them as subtle.

But other ideas on how to make this distiction even more clear are

One option is to have some kind of "banner" at the top clearly stating that the is not official. For example, https://www.dmv.org/ does this, due to the (understandable) confusion that might arise. I'm not saying that the banner would have to be quite this "loud" (all caps, etc.), but something like this is one idea.

---

After considering this a bit more, I think that making a whole new website might be overkill. Even if the initial setup is made "easy" by just copying and tweaking the Qubes website, there will still be ongoing maintenance required, which might be hard since it's all volunteer-based. There could easily come a point in the future when something breaks and no one has time to fix it, so it remains broken for an extended period of time while the doc pages are unreadable by the general public.

Instead, why not take a low-maintenance approach by simply using what GitHub already gives us? Here's a random example doc from https://github.com/Qubes-Community/Contents/:

https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/zoom_dispvm.md

When you view this page, the Markdown is rendered very similarly to the way it would appear on the Qubes website (or on the new website we're considering). It's as readable as any normal website, and it's clear that this is not the official Qubes website, so there's no risk of confusion. Moreover, it requires zero maintenance, since rendering the Markdown this way is built into GitHub. Only the underlying Markdown files and Git repo have to be maintained as usual.

Moreover, this makes it very transparent when we're linking from qubes-doc/doc.md to docs in https://github.com/Qubes-Community/Contents/. We just link to the master branch (as in the link above), and it automatically reflects the latest version as the underlying file gets updated. Since we're not messing around with custom permalinks or redirects, there are fewer things that can go wrong, fewer dead links, less overall hassle and ongoing maintenance burden.

[deeplow]

You have a point @andrewdavidwong. Front the maintenance cost using github it totally the way to go. And for now it might be the most effective solution given there is only one admin and one person who's committing to do the base adaptation and helping with content reviewing from time to time...

The problem with GitHub

The only problem with github it that it's not that great for new users. After literally days lived on github, our brains are wired to parse the website easily. But for a new user, if linked to a README on github the won't see the information right away. First they'll be looking at what's in front of them:

Literally the top half of the screen is wasted with information which the users don't need to be aware of "code structure, issues, searching github, etc."

Github wikis since have less clutter and the editing process is even easier. But unfortunately they have no review process.

edit: So, assuming Qubes is also aimed at vulnerable populations and that external documentation will play a role in supporting those users, the conclusion is that the community documentation should be made also thinking of them. Even if it's not today or tomorrow, I think in the long run it's best for the community docs to have their own easy-to-use space on the internet. (and I think you agree with this).

Maintenance costs

I've had my fair share of maintaining volunteer-run website and I agree it's the kind of job people don't generally like doing (especially fixing stuff). And stuff does break. As the maintainer of the qubes website, I trust you have had your dose of stuff breaking and want us to avoid that (Thanks!).

So, in terms of time @andrewdavidwong, how much overhead would you say this has, compared to github? (from past experience) assuming no new features would be introduced, only maintenance of docs on an external repo (and associated updates on this one). Have core components of the website broken so badly they'd become unusable without a fix?

---

This might not have any effect for colorblind users or users on text-based or other types of web browsers.

Yes, the chosen color (~teal) should be seen well by about (99% of the population), picking up from a long-standing usability question of qubes. But another one may be chosen to even ease this distinction more.

And for text based-browsers the banned idea (as implemented in the docs) should work. But for those browser that will be a problem if the qubes community have a website anyhow.

These changes are good, but some might view them as subtle.

Hum. I'm kind of out of ideas for now. Unless we do some drastic CSS modifications, I don't see another way of making it even more clear. (maybe a simple coloring of the banner bar?)

Thanks for your input @andrewdavidwong

[andrewdavidwong]

But for a new user, if linked to a README on github the won't see the information right away. First they'll be looking at what's in front of them: [...] Literally the top half of the screen is wasted with information which the users don't need to be aware of "code structure, issues, searching github, etc."

But that's mainly because you didn't link directly to the README.md. If you do that, you won't see as much other stuff on top:

https://github.com/Qubes-Community/Contents/blob/master/README.md

So, assuming Qubes is also aimed at vulnerable populations and that external documentation will play a role in supporting those users, the conclusion is that the community documentation should be made also thinking of them.

I'm not quite sure how to interpret this. There seems to be an underlying assumption that the GitHub interface is not sufficiently user-friendly for vulnerable populations. This is an interesting empirical question, and the answer is far from obvious to me. It seems fairly obvious to me that the Markdown documents, when viewed on GitHub, are quite readable to most adult humans (example from earlier). Sure, there's some stuff above the main textual content that they might not understand or might find distracting, but it's easy enough to tell people to ignore that. All you have to do is show them one example. ("The content you want is here; ignore all this other stuff out here.") Since all the doc pages look the same, that one example would suffice. I see far worse on popular mainstream websites, apps, and OSes on a daily basis, yet people seem to manage just fine. To be perfectly honest, Qubes is nowhere near the point where someone who can't find the instructions they're looking for on that page will be able to use Qubes safely. At this point, I think we're talking about remedial computer skills, not even being tech-savvy. (To be clear: This is absolutely in no way meant to be derogatory toward people who lack computer skills. We've all been there. There is never any shame in being a beginner.)

Even if it's not today or tomorrow, I think in the long run it's best for the community docs to have their own easy-to-use space on the internet. (and I think you agree with this).

When phrased this way, I don't think anyone can disagree with such a statement. The question is what can be achieved with a limited workforce and resources. Is it better to have something that's "just okay" but to have it sooner? Is it better to have some "great" even if it takes longer? That depends on countless things, like your goals and how you define "great." At this point, I think the discussion probably gets too abstract to be of practical utility.

So, in terms of time @andrewdavidwong, how much overhead would you say this has, compared to github? (from past experience) assuming no new features would be introduced, only maintenance of docs on an external repo (and associated updates on this one). Have core components of the website broken so badly they'd become unusable without a fix?

We have CI scripts that automatically notify me when builds fail, when there are bad links, etc. Usually this is caused by an update that I push, sometimes by someone else's PR. Then I go in and fix it. I'm not sure whether the community site would have that kind of infrastructure or who would set it up (you?). Over time, the community site would slowly drift away from the official site, unless someone is pulling new changes that I push to the official site. If the only thing being changed on the community side is doc text, then probably nothing will break, but I'm not sure if that can go on forever. Eventually, someone will probably want to change more than just doc text (kind of like you right now 🙂), at which point more work will be required, possibly a lot more.

Ultimately, of course, the decision about whether to set up and maintain a website is a decision for Qubes-Community, not me. I cannot commit to providing any time to helping to maintain such a site. Part of the impetus for moving external docs out of qubes-doc is that there's just too much in qubes-doc to manage. Quality suffers when there's more content than we can maintain and more PRs than we can review in a timely fashion. Also, given the fact that you can install almost any kind of software in Qubes, there's a practically unlimited amount of documentation that can be written. I think it makes more sense for the official docs to follow the Unix philosophy: "Do one thing, and do it well." I.e., have the official docs focus only on Qubes itself -- on the code output by the Qubes OS Project -- and make sure it's accurate and high-quality.

Hum. I'm kind of out of ideas for now. Unless we do some drastic CSS modifications, I don't see another way of making it even more clear. (maybe a simple coloring of the banner bar?)

Well, I'd just refer back to what I wrote above:

One option is to have some kind of "banner" at the top clearly stating that the is not official. For example, https://www.dmv.org/ does this, due to the (understandable) confusion that might arise. I'm not saying that the banner would have to be quite this "loud" (all caps, etc.), but something like this is one idea.

[deeplow]

At this point, I think the discussion probably gets too abstract to be of practical utility.

Thanks again for taking the time to reply. Let's keep it down to earth. I agree with you that for now, doing things on github may be the best given the resources or lack-thereof but...

If the only thing being changed on the community side is doc text, then probably nothing will break, but I'm not sure if that can go on forever. Eventually, someone will probably want to change more than just doc text (kind of like you right now slightly_smiling_face), at which point more work will be required, possibly a lot more.

There would certainly be temptations. I guess installing this on the repo should should remove any such temptations. And complement that with information on the README that only content-wise contributions are accepted. That way we could focus solely the resources on the content.

---

Ultimately, of course, the decision about whether to set up and maintain a website is a decision for Qubes-Community, not me. I cannot commit to providing any time to helping to maintain such a site.

Let's see if anyone else has something to say.

Even if it's not today or tomorrow, I think in the long run it's best for the community docs to have their own easy-to-use space on the internet. (and I think you agree with this).

When phrased this way, I don't think anyone can disagree with such a statement. The question is what can be achieved with a limited workforce and resources.

Sorry. I shouldn't have phrase it like that. See the next reply.

There seems to be an underlying assumption that the GitHub interface is not sufficiently user-friendly for vulnerable populations. This is an interesting empirical question, and the answer is far from obvious to me.

The markdown rendering is very easy to view. But this question is highly non-trivial. I brought this up out of my own anecdotal experience. Many years ago, I kept avoiding coming to GitHub, even for looking for information because all the "pull requests" and other jargon looked daunting. And after all, it was something just for "coders" (or so I thought) and I was not one.

It seems fairly obvious to me that the Markdown documents, when viewed on GitHub, are quite readable to most adult humans (example from earlier).

Yes, this does indeed look a lot cleaner. But there's still that "geek-stuff" at the top. But it's certainly better than nothing!

Well, I'd just refer back to what I wrote above:

Oh... That banner! Our brain does tricks on us. When I visited the website I only saw the COVID-19 banner 🤦. Now I see the one you mean.

We have CI scripts that automatically notify me when builds fail, when there are bad links, etc. Usually this is caused by an update that I push, sometimes by someone else's PR. Then I go in and fix it. I'm not sure whether the community site would have that kind of infrastructure or who would set it up (you?).

Food for though. For now, not having that would be the same as doing it fully GitHub so I guess we could pass on it for now.

[awokd]

Can Qubes-Community.github.io be configured to basically just be a cleaner face on top of the blob content, so it wouldn't need maintenance apart from any drastic underlying Github changes? Not even sure that's an intelligent question...

We do have a folder for code already, could add another for images easily enough.

[deeplow]

Can Qubes-Community.github.io be configured to basically just be a cleaner face on top of the blob content, so it wouldn't need maintenance apart from any drastic underlying Github changes? Not even sure that's an intelligent question...

We do have a folder for code already, could add another for images easily enough.

Sorry for the delay.

This is basically my proposal approach. Doing it all on the same repo would be ideal for maintenance purposes (no need to have to constantly update one with the other).

We do have a folder for code already, could add another for images easily enough.

My only reservation is about adding images to the same git repo. In order to contribute people will have to fork the repo and images will make that super heavy. If you try cloning https://github.com/QubesOS/qubes-attachment/ you'll see what I mean.