Improvements to FAQ page for findability

[ninavizz]

Per #6835 this issue is to improve the FAQ experience. This issue covers items 5 and 11 in the punchlist.

The problem you're addressing (if any)

1. Many folks new to Qubes email questions to the core team, or post on GitHub or in Forums, things already covered by the FAQ. Likewise, few seem to discover the "Steps to resolve common problems" that are thoughtfully documented as FAQs in the Help section of the docs, today.

2. The FAQ page is currently a massive trove of amazing content. Unfortunately however, it is present in the docs as a lengthy .md file. .md is a great format for pages within the docs that advanced users might desire consuming in Terminal apps.

Unfortunately, lengthy text-only pages without progressive-disclosure enhancements or advanced text formatting to make visual hierarchies clearer, are difficult to consume for many users. Likewise, content in the middle of a text-only page of H2s and paragraphs of body copy is not where users have been trained by other online information-consumption experiences, to find high-level questions.

The solution you'd like

1. Accordions are a great pattern for surfacing content such as FAQs, without overwhelming users by the volume of content present on a page when all the answers and questions are visible at all times.
   • Requirements
   • Page w/ accordions must be A11y friendly & deliver an elegant experience with screen readers. Good article.
   • Accordion must not mask content from users querying terms on pages in a search.
   • Accordion must be capable of "gracefully degrading" to an "All Open" state for users who've disabled Javascript.
   • The borderless multi-select accordion from the USDS styleguide meets all of the above.
   • If this might be implemented without requiring calls to any US Government servers, it would be my preference to use. That is a big caveat, and regrettably non-negotiable.
   • If the USDS accordion cannot be implemented w/o calls to a USGov server, and the Boostrap 5 accordion might be done in an ARIA compliant fashion—and with the same graceful degradation properties as the USDS accordion, I'd be ok with that.
2. Per 6835 the "How to resolve common problems" content is proposed to be moved to a TBD "Help" page, outlined in #6963 as an accordion on that page. As such, the website needs an A11y friendly accordion widget implemented; and one that does not mask content from users querying pages in a search.
3. Per comment on 6835, Andrew suggests it might be easier to create an FAQ page outside of the docs, for moving the FAQs into HTML from .md. a. It would also be my preference to see the FAQ live outside the docs, per this mockup. b.Alternately: if an accordion could be incorporated into the docs and the header for the docs could be changed to reflect this three-step breadcrumb design, I'd be ok with the FAQ remain in the docs.
4. Create new groups to add to existing groups, such that the FAQs are grouped by: General, Hardware, Using Qubes, Security, Architecture, Project, and Developers. Order FAQs within each group, as shown in mockup. Note: @andrewdavidwong I have no idea what the most meaningful ordering of the developer FAQs... I ordered the others, per

The value to a user, and who that user might be

1. Folks new to Qubes, or only Qubes curious. These folks are more likely to be looking for answers to questions in a web browser, than in a Terminal app.
2. Funders or donors interested in looking at the website to get basic project information, or to get a measure on project maturity.
3. Folks (users or support providers) familiar with Qubes, looking for answers to basic questions one might not think to find answers on, in project docs.
4. Folks unaccustomed to FOSS norms of including critical project information in "docs" vs a more consumer-friendly website. Yes, Qubes OS attracts many folks from outside the FOSS community, because of its unique security properties.

[DemiMarie]

Can CSS clicked vs not-clicked be used to make the accordion work with JS disabled?

[ninavizz]

@DemiMarie I do not know, that is a GREAT question! Unfortunately all page-content needs to be moved each time a box is closed or opened—so I suspect not. But, I will ask the volunteer working on this!

[ninavizz]

OK! @svensemmler @andrewdavidwong How to do an FAQ page without accordions, yet is still easily usable to consumer-product "trained" folks new to FOSS, has been heavily on my mind these past few weeks. Then I just came upon Standard Notes' help section, and was delighted. What do you both think of this general paradigm for Qubes?

Yep, I've already pitched an extension to 7 categories. Since our FAQ is still probably smaller than Standard Notes, I may not favor putting each category on its own page... but as a way of doing the "ToC style" of FAQ, I really liked how they do this.

https://standardnotes.com/help

Also been reading-up on non-accordion options https://www.nngroup.com/articles/faq-ux-deconstructed/ and https://www.nngroup.com/reports/strategic-design-faqs/

Pls also know that as much as I'll always "defend" my design decisions, I don't always believe those defenses can hold-up—and that I do listen (and want to do a better job of it, always).

[andrewdavidwong]

Then I just came upon Standard Notes' help section, and was delighted. What do you both think of this general paradigm for Qubes?

They're using one page for all the questions (as links) and a separate page for each answer (linked from the main page). It's fine, but it means you can't Ctrl+F on a single page to search through all the answers, and it means making a lot of new pages (one for each question-and-answer). I'm not saying those are deal breakers. I'm just pointing out the trade-offs. Every option has a different set of trade-offs.

[SvenSemmler]

As @andrewdavidwong pointed out having all answers on a single page allows Ctrl+F for those who wish to use it. Having a separate TOC page potentially divided into meaningful sections / categories should ease navigation.

Something like this:

[FAQ Entry Page]

• General
• Hardware
• Using Qubes
• Security
• Architecture
• Project
• Developers

[FAQ TOC Page]

• lists all questions grouped into the above categories
• the category headers are linked from the entry page so one arrives at the respective category automatically when the page is loaded
• Ctrl+F over all questions works

[FAQ Answers Page]

• lists all questions and answers
• Level 1 headers are the categories
• Level 2 headers are the questions (linked from the TOC page, so when clicked there the answers page loads and jumps to the correct entry)
• Ctrl+F over all questions & answers works

I think this would be a good solution that is relatively easy to navigate for the novice (using browser back button and/or links on the page to select categories/questions) jumping back and forth between TOC and Answers page (caching and pre-loading of modern browsers will make this very snappy even on slow connections). On the other hand we are preserving all the advantages the more text oriented crowd will value.

Last but not least the above will be easy to maintain (in MD, in github, version controlled etc.).

[andrewdavidwong]

As @andrewdavidwong pointed out having all answers on a single page allows Ctrl+F for those who wish to use it. Having a separate TOC page potentially divided into meaningful sections / categories should ease navigation. Something like this: [...]

Wouldn't this require a lot of duplication of content? Either that or perhaps putting the content in includes then composing those includes together to form each page, but that would result in several more layers of indirection, which might make things a bit confusing for contributors. Again, I'm not saying those are deal breakers. I'm just pointing out the trade-offs. Every option has a different set of trade-offs.

[SvenSemmler]

On 11/11/21 19:50, Andrew David Wong wrote:

Wouldn't this require a lot of duplication of content?

Can't we reuse the HCL code/mechanism and have YML files in a repository for questions/answers?

---

question: | What is Qubes OS? answer: | Qubes OS is a security-oriented operating system (OS). ...

... then have the respective TOC and answers pages generated?

-- public key: https://www.svensemmler.org/2A632C537D744BC7.asc fingerprint: DA59 75C9 ABC4 0C83 3B2F 620B 2A63 2C53 7D74 4BC7

[andrewdavidwong]

Can't we reuse the HCL code/mechanism and have YML files in a repository for questions/answers?

That'd effectively be the same thing as I was describing.

[SvenSemmler]

That'd effectively be the same thing as I was describing. Great!

might make things a bit confusing for contributors

Maybe the YML approach would actually be easier on contributors. In any case, if you are seeing the need or are looking for an "FAQ maintainer" ...

1) making sure the entries are formally correct, unique and otherwise conform to rules defined by the project 2) manages the review with core team member(s) 3) submits PR or maintains respective repository

... I'd be willing to add this to my workload.

-- public key: https://www.svensemmler.org/2A632C537D744BC7.asc fingerprint: DA59 75C9 ABC4 0C83 3B2F 620B 2A63 2C53 7D74 4BC7

[andrewdavidwong]

Maybe the YML approach would actually be easier on contributors. In any case, if you are seeing the need or are looking for an "FAQ maintainer" ...

1) making sure the entries are formally correct, unique and otherwise conform to rules defined by the project 2) manages the review with core team member(s) 3) submits PR or maintains respective repository

... I'd be willing to add this to my workload.

Thank you. That would be wonderful. :slightly_smiling_face:

[ninavizz]

SVEN!! Thank you. <3

So—just so I am correct... there would be a single YML file for all of the "data," and then the FAQ page would just call-up items by some kind of an automated system—and that could work with 5 or 6 categories for FAQs (yes, there are only a fewe, currently, but I'd like to extend that to the categories shown above)?

My week this upcoming week is slammed, and updates to get to Marta on the AppMenu are my QubesOS priority—but next weekend I should be able to get a concrete mockup together, to reflect what's been discussed, here.

I (immensely) dislike the overwhelming of a single page with such a volume of content; and yet also feel the need for Ctrl-F access to information, is important. Would it be possible to include a search field at the top of an FAQ page that would query the whole YML file? I'd thought for some reason the StandardNotes FAQ had whole pages for categories of questions and answers, but on second glance have noticed it's a unique page for each question and answer. Which, I agree, feels like a maintenance nightmare.

[andrewdavidwong]

So—just so I am correct... there would be a single YML file for all of the "data," and then the FAQ page would just call-up items by some kind of an automated system—and that could work with 5 or 6 categories for FAQs (yes, there are only a fewe, currently, but I'd like to extend that to the categories shown above)?

It sounded like the idea was to have each FAQ entry in a separate file, but it is probably also possible to have them all in one file and address them individually.

I (immensely) dislike the overwhelming of a single page with such a volume of content; and yet also feel the need for Ctrl-F access to information, is important.

Yep, same.

Would it be possible to include a search field at the top of an FAQ page that would query the whole YML file?

That seems to be the standard way that other sites do it. I'm just not sure how to do that (without JavaScript).

I'd thought for some reason the StandardNotes FAQ had whole pages for categories of questions and answers, but on second glance have noticed it's a unique page for each question and answer. Which, I agree, feels like a maintenance nightmare.

Well, if Jekyll can dynamically generate the pages from the YML files (or whatever source data), then perhaps it might not be necessary to manually maintain a bunch of separate pages. That's just a thought; I don't know off the top of my head how feasible it'd be to implement.

[ninavizz]

Ok, coming back to this after several months, via a fabulous volunteer helping get these changes built. Per the above discussion, I did this prototype to demonstrate:

• Keeping Ostrich-Sans/Open-Sans font usage per existing site
• Keeping the 4-bucket accordion on the new Help page
  • Pattern the Figma doesn't reflect: existing open accordions always remain open when a new accordion is opened.
• Redo the primary FAQ page to ditch the accordions per above discussion points
  • Note: Subtle styling on the "Questions" to keep large volume of listed items easy and inviting to consume. Different from standard website a: styling
• Additional small things done for general usability enhancement:
  • On the "Help" page, see how FAQ link in first paragraph is styled; update standard a: styling to reflect that. Existing styling of making things gray on hover, is awful for accessibility and general usability. Prototype shows the text changing to a slightly brighter blue, with a light blue background and a dotted underline. Not sure if that's too fancy for our volunteer, but at some point I'd like to do it.
  • Change "Introduction" to "Overview" as the Navbar title, page name, and H1; not sure if that would break things? More accurate/fitting for website content; books and documentation have introductions... and the Qubes OS website is slowly evolving into a "website," from "documentation." Both of which, are formatted to meet different user mental models of content organization.

@andrewdavidwong @SvenSemmler @deeplow I'd love to get you guys' feedback on the FAQ and Help pages at the above prototype link! The volunteer is working on this stuff, now, so the sooner the better. TY all for all the thought on stuff & helpful feedback thus far.

[deeplow]

Looks really nice @ninavizz. Not much more feedback than that. The index and categorization really make the difference.

The only other thing would be to change the title to "Frequently Asked Questions" as it will probably help with the translations as well has make some few lost souls finally find the meaning of FAQ.

[andrewdavidwong]

Pattern the Figma doesn't reflect: existing open accordions always remain open when a new accordion is opened.

This seems a bit odd and contrary to way websites usually work, no?

I would get rid of the "Unofficial channels" section. There are a potentially unlimited number of unofficial channels that people could make, and we don't want them pestering us with requests to add theirs to this list for "visibility."

Also, Qubes does have an "official presence" on Twitter, Facebook, Reddit, and LinkedIn, but pretty much only for sharing links to our own news posts. (The subreddit itself is unofficial, but I'm a mod there and post official news links there. The other three are our accounts/pages.)

The "Enterprise Support" email address seems dangerous. A ton of non-enterprise users will hammer that address in the vain hope of getting someone else to fix their problem for free. "Public or private business of any size" includes independent contractors. Maybe we need to make it clear that it's paid support and is unlikely to be suitable for small budgets.

[ninavizz]

This seems a bit odd and contrary to way websites usually work, no?

They can work either way, and have shown in testing to be much less annoying for folks when they remain open, after a user has opened a bucket. If it's a "marketing" experience (eg: people are trying to sell you stuff), how they're trying to manipulate your behavior is likely a goal—but for pure usability, recent reading and Sven's on assertions, both point to keeping an information drawer open after a user has chosen to open it, and only closing it when they choose to close it.

I would get rid of the "Unofficial channels" section. There are a potentially unlimited number of unofficial channels that people could make, and we don't want them pestering us with requests to add theirs to this list for "visibility."

Roger that!

Also, Qubes does have an "official presence" on Twitter, Facebook, Reddit, and LinkedIn, but pretty much only for sharing links to our own news posts.

Yep, scroll down to see new footer! "Community" implies reciprocity—so I wanted to keep "community" stuff in its bucket, and then all the other pure-presence stuff, on the "Find Us" section in the footer.

The "Enterprise Support" email address seems dangerous.

It was ITL's direct suggestion. Will connect with you privately on this.

[unman]

I'd add to this that users may want to refer to a number of them at the same time. If the accordions automatically close users will have to keep flicking from one to the other, and have them opening and closing. On the Help page this isn't such an issue, as the entries are few and close. On the FAQ page it would be ridiculous. Against that is the pain of having a large amount of information exposed at the same time, most of which is not relevant to the user's needs. I think that the proposed FAQ suffers from this.

If I understand the layout (probably not), there are grouped links at the top of the page, any one of which will open the relevant section at the bottom of the page and jump to the related answer in that section.

This means that a user will be located in a block of text, but will have to scroll back to the top of the page to get to the questions, or just flick read through a wall of text, to find questions and relevant answers. I cant believe that in practice this is a good solution. Where is the advantage over the current page?

[SvenSemmler]

On 2/2/22 03:28, Nina Eleanor Alter wrote:

I'd love to get you guys' feedback on the FAQ and Help pages at the above prototype link!

Very nice & clean! I assume the accordions default to open when there is no JS -- right?

On 2/3/22 06:04, unman wrote:

This means that a user will be located in a block of text, but will have to scroll back to the top of the page to get to the questions, or just flick read through a wall of text, to find questions and relevant answers.

Each answer has a "back to the top" link next to it's title, which allows to return to the question section.

-- public key: https://www.svensemmler.org/2A632C537D744BC7.asc fingerprint: DA59 75C9 ABC4 0C83 3B2F 620B 2A63 2C53 7D74 4BC7

[andrewdavidwong]

I'd add to this that users may want to refer to a number of them at the same time. If the accordions automatically close users will have to keep flicking from one to the other, and have them opening and closing. On the Help page this isn't such an issue, as the entries are few and close. On the FAQ page it would be ridiculous.

Oh, those. Sorry, I was thinking this was about the nav bar menus for some reason. Yes, having these stay open makes sense.

[ninavizz]

@SvenSemmler Yes, and thank you! The Accordions currently in the test-site, are all CSS I believe—but yes, I can double-check!

@unman Repeating Sven's response, there is a "Return To Top" link to the right of each "Question" in the loooong section of answers—which are grouped on the bottom part of the page, but the groups are not within accordions and are always open. Clicking on the "Return To Top" link returns to the user to the section the question belongs to, at the top of the page. Probably the first 1400px of space after the H1, are just questions; split across 6 categories, and shown in a 2-column layout as hyperlinks.

MUCH easier for a user to discover content, and to find the specific question or realm of questions, to meet their needs, quickly.

The advantage over today's FAQ, is that today you have to read the whole thing to find your question. Developers I suspect, naturally do Command-F; but not everyone that visits the site is a developer. So, nobody bothers to read the whole thing. Also, the current FAQ exists w/in the information-architecture of the docs—which can be confusing to users new to FOSS.

The redesigned page "chunks" content to better promote discovery of information w/o a keyword search, and does follow UX best practices on FAQs. While also working hard to meet the needs of developer consumers.

A lot of balancing going on to not exclude anyone, while also delivering a better experience (outside of the command line) for everyone.

[ninavizz]

@andrewdavidwong Nav bar menus is not at all on the radar for the near-term. "Aack, nobody can find what they want and are emailing us" is the first nut to crack, as is giving visibility to paid support as an option. Next-up, per a different issue @mfc cc'd me on, I think is how to differentiate identifying partners, from media praise.

[unman]

I obviously wasnt clear - link/scroll makes no difference. The user is flip flopping between answers and questions, or skimming the block of text to find questions, just as know.

The FAQ pages used to be broken up in to separate pages by target audience, and structured like classic FAQs. Question Index at top, and Questions/answers below. Questions were grouped by Topic - General, Installation, Problems. Each question linked to a question/answer pair which was in the common section.

All we are doing is returning to that, but with a single page and hiding sections. Why not revert to the original model? Everything User on a User page, with grouped index at top and solutions grouped by category below. No eye candy. All the cited "easier to discover content" advantages AND Ctrl+F search the whole.

[ninavizz]

I purchased a Nielsen/Nelson report on FAQ best practices, and found this part to put words my head couldn't put language to but has been nagging at my noggin this whole time:

"The big problem with a search-only approach is that your vocabulary and your users’ vocabulary probably talk past each other. Regrettably, most people are also not skilled at forming effective search queries."

Especially with facilitating Qubes' adoption by enterprise orgs, unskilled infosec enthusiasts, hobbyists wanting to learn, or human rights defenders—the "browsing" experience of the FAQ table, is essential.

It continues:

"Web teams that understand these problems can adjust their search engines and their website content to help people find what they need, rather than what they ask for. Site-search log analysis and search-results tuning should be part of any web- usability effort, but many web teams don’t (or can’t) manage their website’s search engine well, so people often get no relevant results when they search. Worse, the more “advanced” the search, the less likely it is for people to get any results at all.

Because you need to know what users’ FAQs are in order to tune your search results, you might as well show the current FAQs in order to provide the best service. Some websites use quicklinks, a kind of first-aid navigation shortcut list, as a way to work around poor search results or outdated navigation structures. An FAQ may be more practical, however, because it offers more context than a list of links as well as room to talk about the topics. Your FAQ content can also be usefully indexed by search engines."

[ninavizz]

Ok! I've created a "wiki" GitHub page on my own GH, to have a collaborative/sandbox environment for organizing and editing all of the FAQ content, to meet the new design schema proposed in last week's Figma, that everyone seems into. :)

https://github.com/ninavizz/ninavizz/wiki/Qubes-FAQ-Migration-Content-Prep

I'm hoping everyone in this issue is able to contribute to that MD wiki file. If there is interest in helping me work on this migration of the existing content into the new organization/presentation (note: the tables on the wiki page are my fudging of the nicer two-column layout the end page will have) before a PR is opened with the new formatting in place, I welcome everyone here to pitch on in!

Only not creating a wiki in the Discourse group, as per other discussions around the website, I'd like to restrict contributions to this to core & longtime community peeps.

[deeplow]

@ninavizz not sure if the wiki is the best approach as I don't see any easy way to make changes to the wiki. But maybe I'm missing something. If that's the case, do let me know.

If that's not the case, then maybe moving it to the README.md. I think that way we can make edits easily even through the UI.