Conduct website UX review and develop action plan for specific website changes

[ninavizz]

The problem you're addressing (if any)

1. Qubes website does not currently present a clearly discoverable option for paid support for enterprise users.

2. Likewise, the website does not clearly enough manage everyday user expectations for what community-managed "support" looks like. Core team members regularly get questions emailed to us. Abuse is occasionally lodged at folks on GH and in forums, too—which for our generous volunteers, is not acceptable.

n°1 and n°2 can both be easily done with clearer positioning in content, and some IA tweeks.

Per offline discussion, creating this issue to document need to address this as time permits.

Describe the solution you'd like

I've researched and worked on these problems with previous gigs, so have some ideas for simple(ish) website updates. After I've wrapped work on the Policies stuff, I'll do some wireframes.

I'd like to also potentially add a level of sub-navigation to our existing website theme. Some dev help executing that, would be great, if the rest of the core team is on board with a proposal via wireframes.

Where is the value to a user, and who might that user be?

• Enterprise users with money: Find a clearly discoverable place to reach-out to chat about paying ITL to support you!
• Everyday users with imposter syndrome about engaging with the community: We're nice, come say hi! We also have a CoC, and hold folks to it.
• Everyday users looking for good customer service: (cough) being reminded what "Community Support" is, and that we'd all love to have a properly funded customer support department. And millions of dollars for other things, too.

Describe any alternative solutions you've considered

Today all of the above is written into the website's content. The problem, is that it's not written in a fashion that is readily discoverable—nor is it presented in a fashion that aligns with common patterns users may be looking for.

Additional context

nope!

---

Relevant documentation you've consulted

nada

Related, non-duplicate issues

negative!

[andrewdavidwong]

Related: #2324

[ninavizz]

The donations page could use some love, too.

[ninavizz]

...oh, and also, research.qubes-os.org should become a proper thing.

[andrewdavidwong]

@ninavizz, why did you change the title back from one that was appropriately specific and descriptive to one that's far too vague and generic? Please stop.

Also, please do not try to tack on additional things. Every issue must be about a single, actionable thing.

[ninavizz]

@andrewdavidwong This is a UX task that will result in subsequent development tasks. That is why I changed the title, because I do not know the scope of the best possible solution—and the solutions I've had in mind, likely would require a number of different small development tasks. This issue is purely to mock-up options, solicit input from the core team, iterate as necessary, and determine a direction the core team (you included) wants to move forward with. Then I'll create separate dev ticket(s) that I can tackle, or others can.

Likewise, design solutions rarely seek to solve one problem in isolation from others. So, what you're identifying as "tacking on" is not technical scope creep. It's developing an understanding of direct and indirect problems that can be elegantly solved together, prioritizing the direct/primary problem (in this case, needing to show paid ITL stuff clearly). n°1 and n°2 above, are directly related. n°3, not so much—so I'm fine making that into a separate dev-only issue for myself.

Happy to discuss more 1:1 if clarification would help.

[andrewdavidwong]

@andrewdavidwong This is a UX task that will result in subsequent development tasks. That is why I changed the title, because I do not know the scope of the best possible solution—and the solutions I've had in mind, likely would require a number of different small development tasks. This issue is purely to mock-up options, solicit input from the core team, iterate as necessary, and determine a direction the core team (you included) wants to move forward with. Then I'll create separate dev ticket(s) that I can tackle, or others can.

Likewise, design solutions rarely seek to solve one problem in isolation from others. So, what you're identifying as "tacking on" is not technical scope creep. It's developing an understanding of direct and indirect problems that can be elegantly solved together, prioritizing the direct/primary problem (in this case, needing to show paid ITL stuff clearly).

Then please communicate that in the title or body of the issue somehow. Otherwise, there is no way for anyone else to know what you intended. We can't read your mind.

To date, there have been a dozen other issues with the C: website, ux, and T: enhancement labels, the vast majority of which are or were for implementing actual code changes on the website, not developing UX plans, so the mere use of this combination of labels was insufficient to communicate your intention. Given this context, it's unreasonable to expect others to intuit what you had in mind not once but twice --- first when opening the issue and again when silently changing the title back to something generic.

On that note, "Website Enhancements" and "Website UX Updates" are textbook examples of terrible issue titles. They simply repeat the words that are already in the labels and provide zero additional information beyond those labels. They do nothing to distinguish this issue from the dozen other prior website UX enhancement issues. No matter the intention behind this issue, they would have had to be changed to a more descriptive title to be in keeping with our issue-tracking guidelines and to be useful to others. Having too many undescriptively-titled issues in our tracker makes it difficult to find what you're looking for when searching, for example, not to mention that others should be able to understand what an issue is about from reading the title.

As you know, one of the main parts of my job is managing this issue tracker, so when I do things like edit titles, add/remove labels, and add/modify milestones, it's just a routine part of my everyday job to try to keep things orderly, helpful, and in keeping with the rules. When you undo my work without even saying anything, that comes across as, at best, uncaring and, at worst, intentionally disrespectful.

I clean up the titles on newly-filed issues all the time. It's just a routine part of my job. Been doing it for years. Everyone who's been around here for a while knows that. So, when I edit the title of an issue you file, either you know it's routine cleanup, or I'll drop a comment explaining why I changed it. In fact, I'll often add a comment like "(Changed the title to be more descriptive.)" I'll typically do that when I suspect the issue reporter is new and may not be familiar with how our issue tracker works or my role. However, you're not new anymore. You're a member of the core team, and you know what my role is. Also, in this case, the title was so obviously undescriptive. For both of these reasons, no note was needed when I edited the title to make it more descriptive.

However, when you silently reverted the change, that was a major problem. (Actually, it wasn't silent. You added comments that didn't mention the title revert at all, which is even worse.) I'm not sure if you realize how incredibly rude that seems. (I know you've mentioned not being accustomed to this sort of digital collaboration, so I'm guessing this may be an unfamiliar aspect of internet etiquette or something.) I honestly wondered, at one point, whether you would just keep silently changing the title back if I tried to change it again, which sounds like a childish game I have no interest in playing. The appropriate thing to do, in this case, is not for you to change the title back but instead to post a comment explaining why you think my title change doesn't accurately reflect your intention and communicating that intention so that we can come up with a title that does.

Now, I'm going to change the title again in an attempt to capture what you said above. Please let me know if you still think it's inaccurate.

[andrewdavidwong]

I've also changed T: enhancement to T: task. As explained in the issue tracking documentation:

• T: enhancement — Type: enhancement. A new feature that does not yet exist or improvement of existing functionality.
• T: task — Type: task. An action item that is neither a bug nor an enhancement.

An issue that's for making an actual change to the website (i.e., the sort of issue that will result from this one) would be labeled with T: enhancement, because the website already exists, and that issue would be for improving it. However, this issue is about conducting a UX review and developing a plan. Neither the review nor the plan exists yet. The work of this issue is to do and create them. They're also not new features of anything. Therefore, I think T: task is more appropriate for this issue.

[ninavizz]

Ok, first stab at this!

Figma prototype here. NOTE: Currently this only supports hovering over main-nav items to show sub-nav items and notes. Figma is terrific, yet a touch limited when working quickly. :)

If folks cannot access Figma, see bottom for ASCII version.

Guiding Principles:

• Funnel users to relevant content by need/interest, with discoverable sub-nav items from the main navigation.
  • It's just not intuitive behavior for folks to associate broad concepts to their need, then scroll through a long single page looking for that thing. They need more specific "starting points" than today's site offers.
  • Per sub-nav best practices, keep visible labels brief for easier discovery.
• Get people into communities for support, and out of emailing project folks listed on "Team" section.
• Express project values.
• Surface paid support as an option.
• More clearly position "Official, Community, External" as 3 types of docs.
• Less boring homepage, but without feeling corporate or glitzy.

Why a sub-nav?

A number of problems have been anecdotally observed over the past several months, that surfacing secondary-level navigation options could easily address.

• "Paid" support as an option is not quickly or easily discoverable.
• The concept of "Community Support" via forums is assumed to be understood by users, with Qubes being a FOSS project; when in fact team members are regularly receiving direct emails and comments in surveys suggesting this to not be the case.
• More clearly surface to folks that "Official" and "Community" documentation are two separate entities that each exist, and more clearly put users on paths to access each.
  • Within "Official" docs, a landing-page from which multiple versions of the docs can be linked-out from. This can either be done as a single RTD repo, or as the docs are done today—with each version of the docs having its own repo.

Yep, a lot of what the above suggests, would involve architectural changes to how the website is structured. Between that, and @andrewdavidwong being the Community Manager (aka bad behavior corrector), his feedback feels most essential to guide this. (yes, Marek and others, too—but have pinged outside of GH to keep this out of usual GH workflows)

@saptaks I'd previously pinged you about thoughts on how to work within Bootstrap/Jeckyl to change the Qubes' website nav to include a sub-nav, as implied in the above Figma—executed as a new row of items below the primary row, and that remains visible when an item in the sub-nav or the main nav are selected... but not visible when the home page is what's visible. And, would obvs collapse nicely with the rest of the site's responsiveness, to a menu in mobile.

Would also love to hear what @svensemmler, @holger, @deeplow, @unman and others whom are active with new users in the forums, think this.

---

ASCII Sketch

Bolded items would be in a row as primary nav items. Descending items would appear in a horizontal row just below the main navigation, not as a menu. In a mobile experience, they'd collapse to become a menu.

About |- Overview (../intro) |- Community (new page) |- Team (../team) |- Partners (../partners) |- Statistics (../statistics) |- Security Center (../security)

News |- Announcements (../news/#topic) |- Articles (new page) |- Press (../team) |- Security Research (../research) |- Talks (../news/#topic) |- User Research (tbd)

Downloads |- Verification (../security/verifying-signatures) |- Requirements (../doc/system-requirements) |- Releases (../news/categories/#releases) |- Installation Guide (../doc/installation-guide) |- Licensing (../doc/license)

Documentation |- User Guides: Official · Community (Each would link to separate entry points for both) |- Code of Conduct (../existing) |- Project Security (existing in docs) |- Developer Docs (existing)

Get Support |- Report Bug (existing) |- Report Security Issue (existing) |- Paid Support (tbd) |- FAQ (../faq) |- Community Support (../doc/support)

Donate (existing)

[deeplow]

@ninavizz The navbar an homepage looks like a very nice improvement.

Once issue I've always found with Qubes it's still a technical system. As such one likely will want to learn more about it, rather than simply download. However, the emphasized button is on download and install. I would argue that place should be for the "Intro page" (or a de-technicalized version of it) and then from the bottom (or side) of that page link to the downloads.

Either way, the "Downloads" are in the navbar, so it's not like it's going to be extremely missed if not shown on the big blue button (:wink:) of the home page.

[deeplow]

Another small note, on the suggested prototype the Qubes logo changes from QUBES to Qubes. The logo change is likely unintended, no? (although I have to say your version looks more readable).

[SaptakS]

@SaptakS I'd previously pinged you about thoughts on how to work within Bootstrap/Jeckyl to change the Qubes' website nav to include a sub-nav

Based on the prototype shared, I would say that it would need certain amount of custom CSS (and probably some JS) code, and won't work by adding few bootstrap classes. Also, even thought a non-JS fallback can be created for the above hover prototype, it won't be the best. Though, I think non-JS users can still visit the individual pages and have the navbar there (which won't involve any JS)

would obvs collapse nicely with the rest of the site's responsiveness, to a menu in mobile.

I am guessing you are thinking of an accordion-type collapse-expand behaviour in mobile? That should be straight forward to implement.

[ninavizz]

@deeplow Yes, the "Intro" page that currently is there, seems more intuitive to move into "Overview" under an "About" menu... and also what would show should the user simply click "About"

[ninavizz]

@SaptakS Oof. Yeah, as with SecureDrop, I'd prefer to not have any JS dependencies—and to do everything purely with CSS. All opened pages should have the sub-nav bar showing as a static asset, but then when hovering over primary-navigation tabs, show the respective sub-nav bars for those tabs. While I can see fiddling that up with hide/show Divs in CSS, how to do it to navigate well with a keyboard and screen readers, I don't know how to do.

I found this, but the codepen is only for the sub-nav, not the full nav: https://getuikit.com/docs/subnav#divider-modifier

[ninavizz]

I found a Jekyll "How To" page, and it explains how to do menus here: https://mycyberuniverse.com/jekyll-bootstrap-dynamic-navigation-highlighting-active-element.html

With a 2-level Navigation (what they're calling what I have) here: https://jekyllrb.com/tutorials/navigation/#scenario-3-two-level-navigation-list

I'm ok doing it as a menu vs as a bar, if that's the only options Bootstrap offers, fwiw. The bar would make things a tad more discoverable, but if kids today only use menus, so be it!

[ninavizz]

Just created this alternate version w/ proper Bootstrap style menus: https://www.figma.com/proto/oMjfKRg1Vjc8NeRF11j2rU/IA-Overview—Menuzz?page-id=0%3A1&node-id=0%3A5&viewport=241%2C48%2C1&scaling=contain&starting-point-node-id=0%3A3

[mfc]

I think these are great proposed changes to the website! a visual to draw the reader in (demonstrative screenshot, etc), great idea :)

i defer to you re: which style of subnav is better

[andrewdavidwong]

It seems unusual to have "About" as the first item. Usually, it's the last, and it would typically have "about the project"-type content. I wouldn't be surprised if many users skipped over it due to the name, assuming (perhaps subconsciously) that it doesn't have what they're looking for.

In accordance with standard practice and user expectations, each menu button itself (the bold headings) should also be a link to some page. (If we didn't do this, there would no longer be a link to the downloads page, for example.) In some cases, it's obvious what the page would be; in others, it's not. "News," "Downloads," "Get Support," and "Donate" would presumably retain their existing links, but what would "About" and "Documentation" link to? Seems like we might need a new page for "About." Would "Documentation" just link to the existing table of contents, with each sub-item being an anchor link on that page?

I'm not the one who originally coded our current nav bar, and I wouldn't immediately know how to implement this in pure CSS. I don't think our existing nav bar is a standard bootstrap thing. Seems to be custom, but I'm not certain.

I'd also be interested in hearing opinions from Marek and other core team members about the proposed changes.

[unman]

On Wed, Oct 06, 2021 at 01:08:49AM -0700, Andrew David Wong wrote:

It seems unusual to have "About" as the first item. Usually, it's the last, and it would typically have "about the project"-type content. I wouldn't be surprised if many users skipped over it due to the name, assuming (perhaps subconsciously) that it doesn't have what they're looking for.

In accordance with standard practice and user expectations, each menu button itself (the bold headings) should also be a link to some page. (If we didn't do this, there would no longer be a link to the downloads page, for example.) In some cases, it's obvious what the page would be; in others, it's not. "News," "Downloads," "Get Support," and "Donate" would presumably retain their existing links, but what would "About" and "Documentation" link to? Seems like we might need a new page for "About." Would "Documentation" just link to the existing table of contents, with each sub-item being an anchor link on that page?

I'm not the one who originally coded our current nav bar, and I wouldn't immediately know how to implement this in pure CSS. I don't think our existing nav bar is a standard bootstrap thing. Seems to be custom, but I'm not certain.

I'd also be interested in hearing opinions from Marek and other core team members about the proposed changes.

Can I say that I loathe pages implemented purely in CSS.

[DemiMarie]

Can I say that I loathe pages implemented purely in CSS.

I don’t have any statistics @unman, but I believe that disabling JavaScript is not uncommon among Qubes OS users.

[unman]

On Wed, Oct 06, 2021 at 05:03:31AM -0700, Demi Marie Obenour wrote:

Can I say that I loathe pages implemented purely in CSS.

I don???t have any statistics @unman, but I believe that disabling JavaScript is not uncommon among Qubes OS users.

No disagreement there.

[ninavizz]

@unman Why do you dislike web pages implemented in pure CSS? @DemiMarie Yes, "graceful degradation" is a common thing with Javascript. Unfortunately it requires more work than just doing everything in CSS, so with SecureDrop where our users are expected to be using Tor on the highest security setting, I've advocated to just do everything in CSS. Honestly wanting to understand where Unman is coming from, on a dislike of pure CSS pages implementation.

@andrewdavidwong All of the recommendations were made in accordance to existing best practices, standard Boostrap component interactivity, and how other (cough, more refined) Linux projects organize their sites. Totally agreed wrt needing to click on a primary menu item and having it take you to a page. That said, horizonal sub-menus as I proposed above, can be hard to sustain... and there's no existing Boostrap theme for it, so Boostrap dropdowns are where my brain is currently at.

"About" the project, or "About" the product—yeah, I hear you. "About Us" vs "About Qubes."

Honestly, I think the giant button on the first page should take users into the Introduction flow—as properly downloading and installing Qubes is such a monumental task that is incongruent with where the homepage "Download Now" button comes from (for things that are easy-peasy to install and try out—which, heh, Qubes is not).

The rationale for how a nav should be organized is rooted less in ontology or pure-logic, and more in aligning mental-models and findability to guide user behavior. So, there's no "right" or "wrong" answers, and a team workshop to nail this is probably the best way to get this in a good place.

Also of note: I'm currently still learning Figma, and chose the Qubes website navigation stuff to learn Figma with—as it felt simple. Of course, it turns out to be more complicated than I'd thought (shocker) so my prototypes are lacking in correct interactivity at the moment. I've also hit a learning wall with regards to debugging my latest version, so to get the IA (information architecture) stuff right among the team am backing off the interactivity to just share static things for the moment.

This is where I'm at right now, fwiw. No interactivity, except for the giant pink triangles I was delighted to get to work after successfully getting the dropdowns to work... and then they decided to not work. This is not QT, that isn't fair. :/

The general idea tho, is that all recommendations would be inline with standard Bootstrap patterns—as I don't feel it's right to burden you (Andrew) with implementing new design things, and I have a breaking point with what I'm willing to learn or ask a volunteer to do. And, really, "design" is less the point of all this, so much as is growing the site navigate better per extended business and project needs that have evolved over the years since Brendan did this design, coupled with observations of how the existing site does and does not correctly guide users (eg: all of us getting direct email, and complaining in surveys that our "customer service" stinks). Yes, also potentially replacing the Ostrich font family, which I dislike because I find it to be legibility-challenged.

Anywho: @andrewdavidwong @marmarek @mfc @marmarta I'd love to do a proper synchronous design review to discuss all of this stuff... as synchronous discussion is a much less time intensive and more productive way, generally, to review stuff like this. If you'd all be keen to do that sometime?

[ninavizz]

Follow-up question: How is the .onion site done? Is it auto-generated from existing HTML? Updating the CSS for text to depreciate to a whitelisted condensed or more narrow font than Helvetica, would also be advised. Yeah, typography in Tor on most-secure setting, is hard.

[unman]

On Wed, Oct 06, 2021 at 01:04:45PM -0700, Nina Eleanor Alter wrote:

@unman Why do you dislike web pages implemented in pure CSS? @DemiMarie Yes, "graceful degradation" is a common thing with Javascript. Unfortunately it requires more work than just doing everything in CSS, so with SecureDrop where our users are expected to be using Tor on the highest security setting, I've advocated to just do everything in CSS. Honestly wanting to understand where Unman is coming from, on a dislike of pure CSS pages implementation.

In the browsers I use most of the time, I find that for many sites CSS interferes with my ability to get to content quickly and read the page. This is probably poor design in the first place.

[ninavizz]

Drafted a quick Design Brief for the team to review, for clarifying goals and intentions around updates to the website's global navigation. This issue touches upon other things, too: such as the handling of the "Hero" module w/in the homepage, and the use of fonts. The Design Brief is focused exclusively on Global Navigation—so, the header and the footer.

If the understanding of problems and goals are not shared among the team as it states, the same will be carried into any design solutions presented—so alignment around the design brief, for the website's global navigation, is probably a more efficient first step, than looking at proper design solutions up-front.

Pls feel free to comment here, on what it proposes wrt updating the website's global navigation. PDF below, for reference too. Design Brief — Qubes Website Navigation.pdf

[SaptakS]

@SaptakS Oof. Yeah, as with SecureDrop, I'd prefer to not have any JS dependencies—and to do everything purely with CSS.

The Qubes OS site already has JS dependencies btw. Since you are using bootstrap, though you are not probably using much of the features that need JS, but the bootstrap.js is being loaded. So just wanted to make that clear.

All opened pages should have the sub-nav bar showing as a static asset, but then when hovering over primary-navigation tabs, show the respective sub-nav bars for those tabs. While I can see fiddling that up with hide/show Divs in CSS, how to do it to navigate well with a keyboard and screen readers, I don't know how to do.

I do think that the bar design is pretty nice compared to menu. And just to be clear, even if you use bootstrap's menu, that does depend on JS, so everything I said still applies, just you don't have to write extra CSS/JS code much. As of keyboard navigation, for such navigations, :focus-within pseudo-selector is needed which has pretty good support apart from in IE and very old browsers. Screen reader should also work with focus-within rules. But given you will now have a bigger navigation, need to add a skip-to-content-link in the very beginning

In the browsers I use most of the time, I find that for many sites CSS interferes with my ability to get to content quickly and read the page. This is probably poor design in the first place.

I feel same may happen with JS also, since they will have CSS anyways and might sometimes have more interference. So I agree that it probably is more of a design decision than CSS or JS.

[andrewdavidwong]

Design Brief

I don't have a strong opinion on the proposed changes. I think the brief shows that we don't really know what will work best and that similar projects all do it differently, including many who do what we're already doing now.

My main concern is with how difficult it will be to implement and maintain the subnavs.

[ninavizz]

@andrewdavidwong I'd thought to create an Issue, specific to the nav—and to both label it "Help Wanted" and to post a note in the community requesting support? Once the styles are done, it's all just <li> items in the code.

The big heavy lift imho, will just be restyling the nav to support a subnav. After that, we can change things up after observing the site in-action for a while. Thoughts? No way, btw, I'd want to impose these changes upon either you or me. :D

[andrewdavidwong]

@andrewdavidwong I'd thought to create an Issue, specific to the nav—and to both label it "Help Wanted" and to post a note in the community requesting support? Once the styles are done, it's all just <li> items in the code.

The big heavy lift imho, will just be restyling the nav to support a subnav. After that, we can change things up after observing the site in-action for a while. Thoughts? No way, btw, I'd want to impose these changes upon either you or me. :D

If we have any web devs in our community who would be willing to help, that'd be great!

[ninavizz]

@andrewdavidwong I'm looking into all of this a tad deeper, and am also realizing that much of the undiscoverable content still lives in the docs. Which makes sense for a young/new OSS project, but not a project with +30k users.

A lot of the content also overwhelms the page (wrt discovery), in a fashion that introducing an accordion to hide/collapse answers and only show "questions" (like on an FAQ page) would help with.

I'm currently looking at how to take all of that content and move it into proper web-pages outside of the docs but still within the existing design system—less the one addition of the Boostrap accordion. Which, we'd also need help implementing (tho would be much easier than the nav).

How would you feel about that? Goal with all of this, being discoverability so we get fewer agitated users in public spaces, fewer crummy issues filed on GH, and fewer direct emails to the team. I'm going to start throwing some wireframes together in Figma, from which the pages themselves can actually be built—but will stop if you object.

[andrewdavidwong]

@andrewdavidwong I'm looking into all of this a tad deeper, and am also realizing that much of the undiscoverable content still lives in the docs. Which makes sense for a young/new OSS project, but not a project with +30k users.

A lot of the content also overwhelms the page (wrt discovery), in a fashion that introducing an accordion to hide/collapse answers and only show "questions" (like on an FAQ page) would help with.

I'm currently looking at how to take all of that content and move it into proper web-pages outside of the docs but still within the existing design system—less the one addition of the Boostrap accordion. Which, we'd also need help implementing (tho would be much easier than the nav).

How would you feel about that? Goal with all of this, being discoverability so we get fewer agitated users in public spaces, fewer crummy issues filed on GH, and fewer direct emails to the team. I'm going to start throwing some wireframes together in Figma, from which the pages themselves can actually be built—but will stop if you object.

Sounds pretty scary, TBH. Moving substantive doc content out of qubes-doc could have unintended ramifications for all sorts of things, such as maintainability, contribution workflow, layouts, localization (?), offline docs, and probably other things that will only become apparent later.

Also, I'm not sure what "'proper' web pages" means, as the doc pages already are proper web pages.

[ninavizz]

@andrewdavidwong As the user sees that content, its included in a "Documentation" context. Which feels very weird. It should be formatted and present "within the regular website," as the user sees it, imho. It also "clutters" up the intro experience to the docs, I feel.

EDITED: With regards to page presentation, if the left sidebar could be removed from the Support and FAQ pages, and each could have their own H1s (to appear outside of the docs) that would basically "fix" what the viewer sees. This is where I'm currently at, if you're curious.

I've finally resolved some of the Figma issues, so you can now navigate to the FAQ and Support pages. 99% of the content is the same, it's just "chunked" better for more discoverable consumption—partially via more sectioning, partially via losing the left-nav from the docs (enabling page layouts with more focus on the immediate content), and partially with the help of an accordion Bootstrap widget.

Again, for young projects, it makes total sense for that content to be within the docs—but with +30k users, it's at a growth point of needing to exist outside the docs. Especially for folks unaccustomed to FOSS.

Is the whole website currently localized?

[ninavizz]

Discoverability of content within the very-long and not very well sectioned FAQ feels like a bigger problem, than it existing within the context of the docs. To resolve that, introducing the accordion pattern is the only technically necessary remediation—the rest, is just implementation within its exiting framework.

Of all the above recommendations, the quickest path towards resolving the most urgent problems—discoverability of how to resolve problems and paid support as an option—occurred to me last night, as being to simply edit the existing navigation at the top of the page. The technical navigation changes (adding a sub-nav and search) I still feel should happen—but they can happen after the core pages they're meant to surface, are implemented.

"Documentation" and "Team" can remain in the footer, with "Documentation" amply linked-to throughout a "Get Support" page. The content on today's "Support" page, I do strongly feel needs to be moved out from the docs and into its own standalone webpage (as shown in the prototype, along with a Contact and updated Team page w/o the Inquiries section).

Would that feel less scary @andrewdavidwong than moving the Support page's content along with the FAQ page's content, outside the docs? Alternately: Keeping the "Staying Safe" section and everything below it, in the docs, but also creating a new webpage for the site that mirrors what the proposed "Support" page in the prototype suggests, above its "Staying Safe" section? That would unfortunately create redundant content between the docs and the website, but the content itself would be much more discoverable to consumer-product trained folks not thinking to look for that content within a project's documentation. And, comments in the the code itself where redundant content exists, to remind folks editing things to edit the other page, too, could also exist.

[ninavizz]

Unrelated to above but also discovered: in Tor Browser on Safest security settings, some images and all font awesome glyphs render as tofu. We discovered this on SecureDrop, too, and replaced everything with PNGs. SVGs are also blocked on Safest settings, so we used PNGs at 300% of their expected size, inserted into the code at 30% so that things wouldn't look fuzzy.

Not what I'd qualify as a high priority change, but wanting to make note. Unfortunately there are no bundled/whitelisted fonts that are condensed, so the text is just going to look wacky as Arial.

[ninavizz]

Punchlist of recommendations from this issue's work

In order of priority, below. Criteria for checkboxes to be checked: below items moved to their own issues for implementation, or agreed-to as won't-do (will also strike-thru latter items). All items below, created from exercise guided by Design Brief.

• [x] 1. Create "Help" page at the site level elevated from docs

  • 6963

  • Per prototype
  • New URL (../get-support) or existing ../support URL. Whichever would mess-up the overall site/docs architecture the least.
  • Formatting in docs currently being limited to Markdown, also makes for a more discoverability-challenged experience.
  • Context matters; it's not intuitive for users trained by consumer products, to look for basic information about how to get support for a product, in documentation. Let alone documentation limited to header level and body text formatting, alone.
  • Ideally a small subset of content from docs would exist on a new website-level page; existing "support" page in the docs is quite long, and maintenance/contribution/l10 issues @andrewdavidwong raises are legit.
  • Prototype shows what I think would be good to have on this page, above "Staying Safe" section—which is where redundancy with docs Help page, begins.
  • Add "Enterprise Support" section to site (vs docs) page. ITL/Qubes could benefit from the revenue, and combination of direct emails to team members w/ Forum/GH/Survey comments, indicate the offering as mentioned in the docs is not discoverable to folks looking for it.
    • Qualify w/in offering blurb, that it's not a "Pay-per-call" service, nor a modest offering—but a bespoke engagement offering really only intended for enterprise customers. Hence, use of the word "enterprise" in the proposed email address.
• [x] 2. Create "Contact Us" page

  • 6964

  • Per prototype
  • Direct emails to team members indicate people do not know where to go to find help with problems. A page that does not include team-member contact information and does include a kind mention that Community Support is what those users should go, seems like a good remediation.
  • Move current "Inquiries" content, there.
• [x] 3. "Inquiries" section removed from "Team" page

  • 6964

  • Per prototype
  • Keep it focused on humans and contributors, not as the one place people can find a human point of contact.
• [ ] 4. Interim Extended Navigation
  • Within existing nav design, remove 2 items and add 2 items.
  • Per suggestion in comment above
  • Put "Help" and "Contact Us" up in the top nav, once those pages are live; remove "Downloads" and "Team."
  • Documentation can be an initial H2 at top of "Support" page (before Main Nav is updated to include a sub-nav), and is also imho easily enough discoverable in the Footer for folks that need it. Team belongs in footer, only.
• [x] 5. Implement Accordion Widget

  • 7005

  • Will make "Recommended steps to solve problems" content much more discoverable on "Help" page.
  • Will also make FAQ content much more discoverable.
  • Will need to adapt this with the help of a webdev, to "just show everything" as open, when no JS is present. Otherwise, Tor "Safest" users will be blocked from consuming content—which would suck.
• [x] 6. FAQ page enhancements

  • 7005

  • Organize page information to make stuff more findable.
    • Categories! Currently there are only a few, and they're not anchor-linked from the top. Recommended categories of General, Security, Architecture, Using Qubes, Project, Hardware, and Developers are included in prototype.
    • Begin FAQ page with an introductory sentence that qualifies the categories—and link to each category from this sentence.
  • Implement accordion widget for all Questions and Answers, such that answers are all hidden by default.
    • Possible to do with a "Hide All" and "Show All" toggle at the top of the page, or at the top of each section. If this were to ever be considered, I'd only recommend the latter and not the prior.
  • Yeah, I'd like this to exist outside the docs, but if that would create other problems—I can live with other page enhancements to improve content discoverability (implement more categories, re-order per frequency of ask, and implementation of accordions), and improved nav making page more discoverable, as the only changes.
• [ ] 7. Footer edits
  • Per prototype
  • Re-order items in lists to better correspond with what information users often request
  • Extend content
  • Reframe content as item #10 goes live
  • Put .onion link in a copy'able block of text, not as a hyperlink. Really bad to potentially leave an .onion in a user's broswer history.
• [x] 8. #7006
  • Would direct users to "Intro" page—which is not common to be navigated to, from a primary nav button.
  • A standard pattern on product websites
  • Only showing a "Download" button implies that Qubes is a thing that is quick to download and easy to install. As such, it feels a taaad misleading that such emphasis is given to the download button, today. :)
• [ ] 9. Replace "Ostrich" font family with "Roboto Condensed"
  • Per prototype
  • Ostrich is very narrow, which makes legibility a great challenge; moreso for dyslexic and vision-compromised folx
  • Per Deeplow's comment up above, "Qubes" is also more legible than "QUBES" per the rule that ALLCAPS is typically not as legible as mixed-case letterforms.
  • Nina also just finds it "globby" and kind of not wonderful. Open to reconsider if anyone feels strong attachment to it—but accessibility points up above, still remain an objective concern.
• [ ] 10. Update Main Navigation w/ SubNav & Search
  • Per prototype
  • Not insignificant but not significant technical lift; harder to do than quickly editing existing nav.
  • Would need a volunteer webdev contributor to make this possible.
  • Unsure what options there are for Search.
• [ ] 11. "Research" page edits
  • Rename in "Technical Research" in the H1
  • Alternately, rename to "Why Qubes?" with an introduction framing that page as technical research that led to why Qubes is what it is.
  • Change icon to speak to security/technical focus
  • Add blurb to frame page content as what has led to technical/architectural solutions in Qubes

Longer-term, not high priority items

• [ ] 12. Replace all FA icons with PNGs
  • All reduce to tofu in Tor on Safest, today.
    • Per work on SecureDrop, replacing each with PNG file generated to 300% of the full size, then reduced to 30% in the code, to budget for pixel-density and resizing w/o degradation.
  • Ok, Nina also prefers some non-FA icons, too. Kinda finds FA a bit "blobby" via overall heaviness and dependence on small-radius rounded corners on what would otherwise be hard angles.
• [ ] 14. Create simpler content for today's "Introduction" page
  • Per Deeplow's comment above
  • Move existing content to a more advanced architectural overview
• [ ] 15. Conceptual illustration for HP hero module
  • I somehow doubt today's empty hero module was intended to remain a long-term thing; it feels like a temporary/unresolved problem for the original designer to solve for later, after they got the site redesign live. Five years ago. :)
  • Demonstrate core values/benefits Qubes offers users. Answer "Why Qubes?" in an illustration.
  • Include UI elements like the qute cubes icons, policies, etc.

[ninavizz]

Random observation: for most projects, it is uncommon for "docs" to be embedded within the main site. TorProject somewhat did this, because historically their docs had been their website—and to create the new website as a consumer-friendly entry experience, they just basically added the new site on top of the old website, and then link to it from the button at the top of the page that says "Documentation." I only know that, because I know the two UX folks that worked on the site redesign.

The traditional website format is more "consumer" and business oriented, whereas the docs format more "user manual" and "developer" oriented. IMHO it's more helpful for usability, for users to have a clear context for what they are navigating—as "docs" navigate differently than "websites," because both target users with different needs (and user needs inform design for usability, more than pure ontology).

@andrewdavidwong I know you're looking into how to resolve how to organize release versions w/in the docs. If you're considering a migration to RTD or some other documentation-specific platform/CMS, I'd advocate in favor of the docs being 100% separate from the website. Faaar easier technical feat to pull-off, and what appears to be a common convention.

Ubuntu, KDE, Gnome, and Fedora all do this—I suspect because they also have very consumer-oriented websites. Debian's website is kind of an extension of its docs, and Tails does exactly what Qubes does—which imho creates some confusion, and is more prone to create confusion as s system is extended, than not.

[ninavizz]

Second random observation: the way the docs currently does its breadcrumb/sub-nav within the broader site is potentially confusing... as it's not really a sub-nav, and it's not really a breadcrumb, and it's not clearly disambiguated as its own artifact from the regular website—apart from requiring the user to notice that its pages have a left-nav (while others do not). Per the "alt faq" version in my prototype, I threw together something that can more clearly/explicitly let users know they're in a whole other experience, while more concretely situating users, there.

Like: clicking on "FAQ" from outside the docs, it is currently quite confusing going to this page—because nowhere, does it tell me explicitly that I am in the docs. I just get this giant "Introduction" H1 next to a book icon, and new left-nav widget for reasons that aren't clear. What am I being introduced to? And, deeper into the docs, I don't know how to get to the "Docs Home."

. . . ...vs this—placing a consistent sub-nav for docs, within the docs—where I feel the context-change is made clearer and more explicit. Also, a functional breadcrumb. This also makes a stronger case for menus, over the horizontal nav, as an subnav mechanism for the main navigation. Keeping the horizontal bar as a device, for just the docs.

EDIT: I just realized all the docs pages are .md files, which limits page layout/formatting opportunities to make pages of dense content more readable. The Expand/Collapse capability w/in markdown is certainly an option.

Yes, it would be a huge lift that's probably not affordable or worth it right now, to migrate the docs from .md files in GitHub. Have they already been translated?

[andrewdavidwong]

Punchlist of recommendations from this issue's work

In order of priority, below. Acceptance criteria for this issue closing: below items moved to their own issues for implementation, or agreed-to as won't-do. All items below, created from exercise guided by Design Brief

• [ ] 1. Create "Support" page at the site level elevated from docs

OK

• Per prototype
• New URL (../get-support) or existing ../support URL. Whichever would mess-up the overall site/docs architecture the least.
• Formatting in docs currently being limited to Markdown, also makes for a more discoverability-challenged experience.

• Context matters; it's not intuitive for users trained by consumer products, to look for basic information about how to get support for a product, in documentation. Let alone documentation limited to header level and body text formatting, alone.

  • Ideally a small subset of content from docs would exist on a new website-level page; existing "support" page in the docs is quite long, and maintenance/contribution/l10 issues @andrewdavidwong raises are legit.
  • Prototype shows what I think would be good to have on this page, above "Staying Safe" section—which is where redundancy with docs Support page, begins.

I'm fine with moving some content, but not duplicating it.

* Add "Enterprise Support" section to site (vs docs) page. ITL/Qubes could benefit from the revenue, and combination of direct emails to team members w/ Forum/GH/Survey comments, indicate the offering as mentioned in the docs is not discoverable to folks looking for it.

  * Qualify w/in offering blurb, that it's not a "Pay-per-call" service, nor a modest offering—but a bespoke engagement offering really only intended for enterprise customers. Hence, use of the word "enterprise" in the proposed email address.

• [ ] 2. Create "Contact Us" page

OK

• Per prototype
• Direct emails to team members indicate people do not know where to go to find help with problems. A page that does not include team-member contact information and does include a kind mention that Community Support is what those users should go, seems like a good remediation.

People will just spam whatever email address they find if they think they'll get the answer they want that way. The business@, press@, etc. addresses get a lot of spam like this already, e.g., people asking how to fix common problems in their Qubes installations. It's always easier to send an email than to register for a forum or mailing list, and from their POV it's a zero-risk gamble, because worst-case we'll either ignore them or tell them off.

• Move current "Inquiries" content, there.
  • [ ] 3. "Inquiries" section removed from "Team" page

OK

• Per prototype
• Keep it focused on humans and contributors, not as the one place people can find a human point of contact.
  • [ ] 4. Interim Extended Navigation

I don't understand what this means, even after looking at the prototype.

• Per suggestion in comment above

  • Put "Support" and "Contact Us" up in the top nav, once pages created.
• Documentation can be an initial H2 at top of "Support" page (before Main Nav is updated to include a sub-nav), and is also imho easily enough discoverable in the Footer for folks that need it.
  • [ ] 5. Implement Accordion Widget

OK

• Bootstrap 5's accordion is what I customized the prototype's accordion, from (visible on Support pg)
• This will also make FAQ content much more discoverable.
• Will need to adapt this with the help of a webdev, to "just show everything" as open, when no JS is present. Otherwise, Tor "Safest" users will be blocked from consuming content—which would suck.
  • [ ] 6. Replace "Ostrich" font family with "Roboto Condensed"

Personally, I never liked Ostrich, all caps, or really the whole look-and-feel of the website design. It just wasn't to my personal taste. But now I'm used to it (and have gradually made some of my own tweaks over the years). But, these things have been part of the branding for such a long time that I'm not sure what the ramifications of changing them would be. It might affect "brand recognition" and related things I won't pretend to know about. If such a change is made, it seems like it should probably be part of some overall "rebranding" thing, however that's supposed to be done. Like those bags of chips that say, "New look, same great taste!" Always seemed pointless to me, but it's so common that there must be a reason for it and a proper way to go about doing it.

• Per prototype
• Ostrich is very narrow, which makes legibility a great challenge; moreso for dyslexic and vision-compromised folx
• Per Deeplow's comment up above, "Qubes" is also more legible than "QUBES" per the rule that ALLCAPS is typically not as legible as mixed-case letterforms.
• Nina also just finds it "globby" and kind of not wonderful. Open to reconsider if anyone feels strong attachment to it—but accessibility points up above, still remain an objective concern.
  • [ ] 7. Add "What Is Qubes?" as secondary HP button, next to download button in homepage hero module

OK

• Would direct users to "Intro" page—which is not common to be navigated to, from a primary nav button.
• A standard pattern on product websites
• Only showing a "Download" button implies that Qubes is a thing that is quick to download and easy to install. As such, it feels a taaad misleading that such emphasis is given to the download button, today. :)
  • [ ] 8. Update Main Navigation w/ SubNav & Search

OK

• Per prototype
• Not insignificant but not significant technical lift; harder to do than quickly editing existing nav.
• Would need a volunteer webdev contributor to make this possible.
• Unsure what options there are for Search.
  • [ ] 9. "Research" page edits

OK

• Rename in "Technical Research" in the H1
• Alternately, rename to "Why Qubes?" with an introduction framing that page as technical research that led to why Qubes is what it is.
• Change icon to speak to security/technical focus
• Add blurb to frame page content as what has led to technical/architectural solutions in Qubes
  • [ ] 10. Footer edits

OK

• Per prototype
• Re-order items in lists to better correspond with what information users often request
• Extend content
• Reframe content as #5 goes live
  • [ ] 11. FAQ page enhancements

OK

• Organize page information to make stuff more findable.

  • Categories! Currently there are only a few, and they're not anchor-linked from the top. Recommended categories of General, Security, Architecture, Using Qubes, Project, Hardware, and Developers are included in prototype.
  • Begin FAQ page with an introductory sentence that qualifies the categories—and link to each category from this sentence.

• Implement accordion widget for all Questions and Answers, such that answers are all hidden by default.

  • Possible to do with a "Hide All" and "Show All" toggle at the top of the page, or at the top of each section. If this were to ever be considered, I'd only recommend the latter and not the prior.
• Yeah, I'd like this to exist outside the docs, but if that would create other problems—I can live with other page enhancements to improve content discoverability (implement more categories, re-order per frequency of ask, and implementation of accordions), and improved nav making page more discoverable, as the only changes.

Longer-term, not high priority items

• [ ] 12. Replace all FA icons with PNGs

OK

• All reduce to tofu in Tor on Safest, today.

  • Per work on SecureDrop, replacing each with PNG file generated to 300% of the full size, then reduced to 30% in the code, to budget for pixel-density and resizing w/o degradation.
• Ok, Nina also prefers some non-FA icons, too. Kinda finds FA a bit "blobby" via overall heaviness and dependence on small-radius rounded corners on what would otherwise be hard angles.
  • [ ] 14. Create simpler content for today's "Introduction" page

OK

• Per Deeplow's comment above
• Move existing content to a more advanced architectural overview
  • [ ] 15. Conceptual illustration for HP hero module

OK

• I somehow doubt today's empty hero module was intended to remain a long-term thing; it feels like a temporary/unresolved problem for the original designer to solve for later, after they got the site redesign live. Five years ago. :)
• Demonstrate core values/benefits Qubes offers users. Answer "Why Qubes?" in an illustration.
• Include UI elements like the qute cubes icons, policies, etc.

[andrewdavidwong]

@andrewdavidwong I know you're looking into how to resolve how to organize release versions w/in the docs. If you're considering a migration to RTD or some other documentation-specific platform/CMS, I'd advocate in favor of the docs being 100% separate from the website. Faaar easier technical feat to pull-off, and what appears to be a common convention.

I'd be fine with that. Might also make sense to have someone else be the website maintainer in that scenario.

Yes, it would be a huge lift that's probably not affordable or worth it right now, to migrate the docs from .md files in GitHub.

Bear in mind that the docs are written in Markdown for a reason. It's one of our major features.

Have they already been translated?

Most of them, I think.

[unman]

On Mon, Oct 11, 2021 at 05:50:24PM -0700, Andrew David Wong wrote:

@andrewdavidwong I know you're looking into how to resolve how to organize release versions w/in the docs. If you're considering a migration to RTD or some other documentation-specific platform/CMS, I'd advocate in favor of the docs being 100% separate from the website. Faaar easier technical feat to pull-off, and what appears to be a common convention.

I'd be fine with that. Might also make sense to have someone else be the website maintainer in that scenario.

I've said before that in my experience RTD is far less open to contributions. As to having a separate documentation area, (e.g support.qubes-os.org), this is supported by GitHub as a custom subdomain. It's quite easy to set up, with minimal impact on current maintenance and contributions.

[ninavizz]

Would support.qubes-os.org be more inline with standards, or docs.qubes-os.org?

[ninavizz]

@andrewdavidwong Ok... so, for translation—are languages then only triggered by IP location? Only confused, as I'd expect a languages picker/dropdown for when a thing is available in a different language. Would it be hard to put one on the docs and/or website?

[ninavizz]

re: Ostrich: Yeah, all-caps is generally not the most legible way to typeset words. Ostrich is also what's called a "display font;" meaning it's highly decorative and not created for legibility, so much as aesthetics. So, at the size it is in the navigation, it's already too small.

When allcaps is used, extra letterspacing is helpful... and it can be a very helpful device to organize content across a webpage.

Ostrich is used in swag, but is not used anywhere in the UI itself. Because it is similar enough to Roboto, and the "Q" feels like the stronger brand-associated visual, I don't think it would be disruptive to do the change on the website.

@marmarek Do you have strong feelings about Ostrich? Roboto Condensed is quite similar, but has crisp terminals and larger counters with slightly different proportions to help with legibility. It is what I used on the homepage and elsewhere, across ye prototype.

[ninavizz]

@andrewdavidwong "Interim Extended Navigation" meaning to

• Remove from the main nav:
  • "Documentation," but leave it in the footer
  • "Team," but leave it in the footer
• Add to the main nav:
  • TBD friendly "Support" page
  • Suggested content, all in above wireframe. Links all point to documentation.
  • MD and docs, combined, are just inadequate to navigate users looking at pages in a web browser.
  • Paid (Enterprise) Support need to be positioned on a friendly webpage to be discoverable.
  • TBD "Contact Us" page
    • Includes "Enterprise Support" ITL email
    • Includes section mentioning forums, for people looking for support, below.

See Pic

I hear your points about human behavior/impatience to want to just connect with someone, directly. It is valid—however, I've worked on this problem for so many orgs, and content structuring can always be optimized to reduce the frequency with which people do it. I am optimistic that the above changes, will reduce the frequency with which it happens—and hopefully also reduce ill-will of frustrated people commenting on surveys and in forums.

[ninavizz]

re: redunant content on a "Support" webpage... based on what I've observed in forums and on survey comments, I do feel that moving the "Support FAQ" content from the docs and to a webpage, would be advisable. Likewise, some redundancy, with descriptive content—but the essentials, like how to sign up to an email list, still living in the docs (and the webpage pointing to do the docs).

Nerds don't need to see the above as much as regular folks do. Its goal, is to bridge the gap between FOSS/nrrds and folks coming into Qubes for its security offerings—while unaccustomed to FOSS norms, and expecting.

Happy to add you as an editor on the Figma doc if you'd like to play with stuff, @andrewdavidwong! It's far easier for me, at least, to do edits there, than in the PR cycle.

[marmarek]

I think the documentation should be easily discoverable from the main page. If not direct from the top navbar, then maybe have "Help" position instead of "Get support" that will include both support channels and documentation link?

[ninavizz]

@marmarek So, this? Figma Link

[marmarek]

@marmarek So, this?

Yes!

[unman]

On Tue, Oct 12, 2021 at 01:49:02PM -0700, Nina Eleanor Alter wrote:

Would support.qubes-os.org be more inline with standards, or docs.qubes-os.org?

Whatever you like.

[andrewdavidwong]

@andrewdavidwong Ok... so, for translation—are languages then only triggered by IP location? Only confused, as I'd expect a languages picker/dropdown for when a thing is available in a different language. Would it be hard to put one on the docs and/or website?

There already is one, but it's not live yet. Search issues with the "localization" label to read more about it.

[andrewdavidwong]

@andrewdavidwong "Interim Extended Navigation" meaning to [...]

Ok, sounds fine to me.