search

QubesOS / qubes-issues

The Qubes OS Project issue tracker
https://www.qubes-os.org/doc/issue-tracking/
536 stars 47 forks source link

Updates to first page of Docs, and how some items are shown in "User Documentation" #6756

Closed ninavizz closed 3 years ago

ninavizz commented 3 years ago

Checklist

The problem you're addressing (if any)

Today's user docs are difficult to navigate. While most of their organization is semantically correct, a lot of it is also not very intuitive. This is one of many incremental changes, to improve that. Also: this issue is being filed, because the primary page on the docs needs editing—and that, I have no clue how to edit. Otherwise, I'd just submit a PR.

Describe the solution you'd like

EDITED to reflect first comment, below documentation_changeto23

For the first page on the Docs, make the following changes: 1. Eliminate all redundant content from what is currently the "Introduction" section on the website and rename that section. This content is discoverable enough on its own, from that tab. Most of it is also tailored to help users decide whether or not they want to use Qubes OS. The Docs, conversely, should be for people who have already chosen to use Qubes, or who want to look things up. Th Docs are the owner's manual, not the commercial on TV or social media campaign—even though there is helpful content, there. The mixed mental models make for a more frustrating experience trying to find owners-manual fidelity content in the Documentaiton, as a user. 2. Re-title the introduction of the Docs, to not conflict with the website section. I've proposed "Welcome!" and feel it works, but am open to something else. 3. Demote ordering of "Project Security" to not come before the more basic and everyday-referenced "User Documentation." For users who just scroll down the page and don't use the TOC on the left, it is confusing and disorienting seeing security stuff detailed, before "How do I turn this thing on and what are the basic parts of it called?" 4. Within User Documentation, a number of smaller changes to improve findability and intuitive recognition of topical content.

User Documentation changes

Using bulleted list formatting, to present updated ordering of items as an ascii-sketch, below (1)

  1. General: Standardize around sentence-case, reserving title-case for inline mentions of specific components or features.
  2. Nix the body copy below the "Qubes OS Documentation" H1 on the first page.
  3. More intuitive phrasing to catch non-technical users' attention, than "Issues Management."
  4. Ok. So... the awesome new "Getting Started" page, I feel is mis-placed in the "How To Guides." It's really that first section in an owners manual that users will keep coming back to again and again, as they're learning Qubes OS, to check their understanding of how all this works and to look-up how to speak to different parts of the UI within Qubes. Likewise, the "References" section today, is not at all an intuitive section for the CLI "handbook" of things. So, grouping both of those pages in the parent group of "Using Qubes OS" or "Get Started" feel like an intuitive title for that initial reference section, but I'm not married to either. Trying to conjure a mental-model that is hybrid reference and "10,000ft view" introduction. Qubes has so much complexity, I suspect users will/do desire having that initial non-upsell-y/persuasive, simple/straightforward 10,000ft-view introduction easily discoverable to keep coming back to.
  5. Renamed "How To Get Started" page. The first section on that page, should be renamed to "Overview" to eliminate redundancy. Yep, I still plan to pepper that section with demonstrative illustrations to break-up the initial (significantly improved!) wall-o-text.
  6. Title case, to reflect "CLI" acronym
  7. All items within "How To Guides" updated to active-voice, and with the central topic/feature listed first. Both are UX best practices for discoverability in Information Architecture.
  8. Introduce a new level of visual hierarchy in the text layout of this page, to give sub-groups to the existing sub-group of "How To" guides. All inter-qube clipboard stuff should be grouped, and all Device Management stuff should be grouped. This group, is for Clipboard stuff. "dom0" as the leading word for the 3rd item, and "text only" as the leading phrase for the first item, are important things for discoverability.
  9. "Device Management" sub-group, at the same level as aforementioned "Inter-qube clipboard" sub-group. Both group names are important, as the introduce phrasing repeated through the docs, that contextually users will be able to learn as being associated with "cut and paste" and the devices/attachment widget.

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

Non-technical users unaccustomed to navigating developer docs, or security-project docs.

Describe any alternative solutions you've considered

Tears.

Additional context

n/a

Relevant documentation you've consulted

Just some UX best practices.

Related, non-duplicate issues

A community-created "Simple User Guide" effort is underway, but the core project guide still needs some love to be more easily navigated with items more findable, per information architecture best practices.

ninavizz commented 3 years ago

Actually, I just realized: on the website, the tab that says "Introduction" really should say What Is Qubes?... partially to match its H1, and also because that's just more aligned with that page's purpose. It's a page that's as much for persuasion, as it is to introduce folks to Qubes.

If that is changed, then what I proposed for Welcome! could remain Introduction, which I feel is a more accurate header for a section in a place the user navigates to from "Documentation," anyway.

andrewdavidwong commented 3 years ago

Also: this issue is being filed, because the primary page on the docs needs editing—and that, I have no clue how to edit. Otherwise, I'd just submit a PR.

For future reference, or in case you were wondering, it's here: https://github.com/QubesOS/qubesos.github.io/blob/master/_data/doc-index.yml

For the first page on the Docs, make the following changes:

  1. Eliminate all redundant content from what is currently the "Introduction" section on the website and rename that section. This content is discoverable enough on its own, from that tab. Most of it is also tailored to help users decide whether or not they want to use Qubes OS. The Docs, conversely, should be for people who have already chosen to use Qubes, or who want to look things up. Th Docs are the owner's manual, not the commercial on TV or social media campaign—even though there is helpful content, there. The mixed mental models make for a more frustrating experience trying to find owners-manual fidelity content in the Documentaiton, as a user.

I'm okay with this and mostly agree.

However, I'm not convinced that the glossary belongs in the introduction, as it's a reference document.

Ideally, we should have hover-over glossary entries (at least) the first time the user encounters each term in the rest of the documentation. This would be better than expecting the user to read through the entire glossary upfront and retain or refer back to it.

We could easily split up each glossary entry into a separate Markdown file (in _includes/?), but it's unclear how best to code the site in a way that will allow those definitions to be accessed organically in other text, especially in a way that also works on mobile devices with no cursor to hover.

Anyway, this should be filed as a separate issue, if it's a desired feature.

  1. Demote ordering of "Project Security" to not come before the more basic and everyday-referenced "User Documentation." For users who just scroll down the page and don't use the TOC on the left, it is confusing and disorienting seeing security stuff detailed, before "How do I turn this thing on and what are the basic parts of it called?"

To be clear, this section is about project security, not security inside of Qubes OS. That's why it appears early, whereas "Security in Qubes" appears much later. Many people who are knowledgeable about security will want to handle these project security topics early in their Qubes adoption process. For example, they might want to make sure we do proper code and ISO signing and understand how we perform that practice before downloading and installing Qubes. Similarly, they might want to convince themselves that the project is trustworthy and hasn't already been compromised before deciding to use Qubes. Various project security topics, such as the canaries, might be relevant here.

In other words, the current ordering makes sense if you understand and care about security, but I can see how it might be confusing to those who don't. Since the types of users I mentioned would be more advanced users who should be capable of seeing that this section is a bit further down in the table of contents (and either clicking the link to be taken there or simply scroll a bit further down the page), I'm ok with this reordering.

  1. General: Standardize around sentence-case, reserving title-case for inline mentions of specific components or features.

A while back, I saw that our docs were inconsistent: some page titles were in sentence case, while others were in title case. I wanted to change them all to sentence case, but I quickly realized that the vast majority were already in title case, and I didn't know how to change them all with an automatic batch operation, so I instead changed the minority that were in sentence case to title case so that they'd at least be consistent.

I'd still like them all to be in sentence case, but, as I said, I don't know how to do this through an automatic batch operation, and it's frankly too much tedious manual effort for me to do it all by hand. It would require changing the title: line in the YAML frontmatter of each doc file. Hopefully, someone will submit a PR that makes this change, whether they accomplish it through automation or by hand.

I suggest opening a separate issue for this. In the meantime, I'll continue to use title case for titles just to maintain consistency until we can change them all to sentence case.

  1. Nix the body copy below the "Qubes OS Documentation" H1 on the first page.

I don't care about the existing body text, but I think it looks bad to have an h2 immediately below and h2 without any body text in between. Can we replace it with something better?

  1. More intuitive phrasing to catch non-technical users' attention, than "Issues Management."

The current title is "Issue Tracking," not "Issues Management." However, I'm fine with using a less technical title in this location. [Edit: Oh, wait. I forgot that we now grab the title directly from each doc file's YAML frontmatter so that the titles are always the same, so this is a no-go. Anyway, there's a "Report a Bug" link on the sidebar on every page, so it should be fine.]

  1. Ok. So... the awesome new "Getting Started" page, I feel is mis-placed in the "How To Guides." It's really that first section in an owners manual that users will keep coming back to again and again, as they're learning Qubes OS, to check their understanding of how all this works and to look-up how to speak to different parts of the UI within Qubes. Likewise, the "References" section today, is not at all an intuitive section for the CLI "handbook" of things. So, grouping both of those pages in the parent group of "Using Qubes OS" or "Get Started" feel like an intuitive title for that initial reference section, but I'm not married to either. Trying to conjure a mental-model that is hybrid reference and "10,000ft view" introduction. Qubes has so much complexity, I suspect users will/do desire having that initial non-upsell-y/persuasive, simple/straightforward 10,000ft-view introduction easily discoverable to keep coming back to.

The intention of our "Reference" section is to contain actual reference materials, similar to dictionaries and almanacs. They're not intended to be introductory in the way "How to Get Started" is.

However, I'm fine with making "How to Get Started" into the introductory page of the documentation.

  1. Renamed "How To Get Started" page. The first section on that page, should be renamed to "Overview" to eliminate redundancy. Yep, I still plan to pepper that section with demonstrative illustrations to break-up the initial (significantly improved!) wall-o-text.

I'm open to the possibility of changing the title of the page and its location in this list, but I'm not a huge fan of "The basics" as a title.

  1. Title case, to reflect "CLI" acronym

This would just be a language mistake. None of the words is a proper noun, so none of the words should be capitalized apart from title casing conventions. For example, "VM" is an acronym for "virtual machine," but neither "virtual" nor "machine" is a proper noun. Just because acronyms are capitalized doesn't mean the words they stand for are also supposed to be capitalized.

Also, in your proposed title ("Command Line tools"), the title is not in title case, since "tools" is not capitalized. This would be correct if "Command Line" were a proper noun phrase, but it's not, so this title would be incorrect no matter what rules we were following.

Also, the current hyphen between "command" and "line" in "command-line interface" is appropriate, since "command-line" is a compound adjective that modifies "interface" in this phrase.

As for capitalizing words after the first in a compound adjective when the whole phrase is in title case, that's a matter of style. Consistency is what's important here. We currently don't capitalize the subsequent words, but I personally think it'd look better if we did, and this is what the Chicago Manual of Style (to which I'm somewhat partial) recommends, so I'll go with that for now. (Of course, this will be a moot point once we switch all titles to sentence case.)

  1. All items within "How To Guides" updated to active-voice, and with the central topic/feature listed first. Both are UX best practices for discoverability in Information Architecture.

A few comments on this:

  1. Active and passive voice apply to sentences. I'm not sure if it makes sense to try to apply them to mere phrases. I suspect not. You've only succeeding in using active voice in (some of) these titles by converting phrases into sentences. It's not like they were in passive voice before or anything.
  2. Your proposed titles inconsistently mix up finite and nonfinite verb forms. Let's take two of your proposed titles as examples: "Updating your system" and "Install software." "Updating" is a gerund that functions as a noun. The form that functions as a verb would be "Update," as in "Update your system." No matter which way we decide to go on this, it's important to be consistent. In other words, consistency requires that these two titles be either (a) "Update your system" and "Install software" or (b) "Updating your system" and "Installing software" (mutatis mutandis for the the other titles).
  3. Your proposal appears to directly contradict this advice (hat tip to @deeplow), specifically here:

    Name guides well The title of a how-to document should tell the user exactly what it does. How to create a class-based view is a good title. Creating a class-based view or worse, Class-based views, are not.

  1. Introduce a new level of visual hierarchy in the text layout of this page, to give sub-groups to the existing sub-group of "How To" guides. All inter-qube clipboard stuff should be grouped, and all Device Management stuff should be grouped. This group, is for Clipboard stuff. "dom0" as the leading word for the 3rd item, and "text only" as the leading phrase for the first item, are important things for discoverability.
  2. "Device Management" sub-group, at the same level as aforementioned "Inter-qube clipboard" sub-group. Both group names are important, as the introduce phrasing repeated through the docs, that contextually users will be able to learn as being associated with "cut and paste" and the devices/attachment widget.

Funny story: One of the first things I did when I initially started working on the documentation many years ago was to make this sort of change. However, shortly after that, Joanna said that the docs were a mess and too hard for non-technical users, so she said that there would be just one flat list of doc pages with no further levels of nesting, and so it has been ever since... until recently. Recently, the localization overhaul had some side-effects, one of which was the subtle (re)introduction of a second level in the list of doc pages. Your proposal would add a third (and we're back off to the races).

There's also a technical issue here, which is that the current website code expects only the current two list levels. Setting aside, for a moment, the question of whether we should introduce that third level, doing so would likely require adding another loop in the code, probably inside of this one.

I suggest opening a separate issue for this.

Actually, I just realized: on the website, the tab that says "Introduction" really should say What Is Qubes?... partially to match its H1, and also because that's just more aligned with that page's purpose. It's a page that's as much for persuasion, as it is to introduce folks to Qubes.

In principle, I'm fine with this. In practice, "What is Qubes[ OS]?" is an awful lot of text to try to cram into the already-cozy navbar. If the user's browser window is a bit narrow, it even takes up two lines. :slightly_frowning_face:

screenshot-localhost_4000-2021 07 03-03_16_37

Also, we'd have to change the title of the intro page, or else it'd be really awkward at the bottom:

screenshot-localhost_4000-2021 07 03-03_17_10

andrewdavidwong commented 3 years ago

I'm open to the possibility of changing the title of the page and its location in this list, but I'm not a huge fan of "The basics" as a title.

However, I'm fine with making "How to Get Started" into the introductory page of the documentation.

Decided just to change the name back to "Getting Started" until we can think of a better one.

Also decided to move it (back?) to the intro section of the docs.

I've done the things that are immediately actionable and that I agree with. The rest either requires further hashing out, should be open as separate issues, or is a no-go. (See my previous comment for details about each thing.)

deeplow commented 3 years ago

Wow. Too much discussion (just skimmed through it).

We could easily split up each glossary entry into a separate Markdown file (in _includes/?), but it's unclear how best to code the site in a way that will allow those definitions to be accessed organically in other text, especially in a way that also works on mobile devices with no cursor to hover.

Perhaps one could add a (non-js) popover with the glossary definition when the user hovers. When they click on the desktop it would open the glossary page and when clicked on the mobile it opens the popover. Not sure how this can be implemented, but I'm sure someone has done it. (this should be a separate issue).

ninavizz commented 3 years ago

@deeplow LOL yes. :) Also, see new issue ^^ :)

@andrewdavidwong 99% of what got Merged and is live, WOW—HOORAY!! Thank you for doing that, and, dang, so quick.

The only (literally) points I feel where we don't see eye to eye, I feel have to do with the "Design Principles" (or goals) the docs aspire to follow. You come from an academic background. Most humans, do not. While the Qubes user community probably has more academics in it than most Linux user communities, non-academics still comprise a healthy chunk of Qubes OS users... and, when they are using Qubes, they come into the docs with mental-models and expectations shaped by consumer product manuals and user guides. "RTFM" is a funny meme, because so often people just don't read the damn manual. Which is both my job security, and the bane of all community managers and support folks.

Information Architecture is very different from Library Science, with regards to best practices in organizing information. The prior, prioritizes human needs. The latter, prioritizes how to organize a wealth of information according to pre-defined systems that have evolved over centuries to best serve researchers and academics (people who spend their days working to make sense of thousands of books and periodicals in libraries). Neither discipline is mutually exclusive to the other, but both prioritize very different goals.

For "Technical Documentation," the prior tends to be more heavily embraced. The end-user consuming that content is also usually a technical professional being paid for their time to learn stuff to support many other people. For "Developer Documentation," standards have just kind of evolved over many years, and those standards just kind of work—mostly, because developers are by nature curious and patient individuals, and they're reading documentation because they want to know the nitty details. For "User Guides," well... every "RTFM" meme that's ever been created, explains that mess of reality.

When one is utilizing an artifact as a researcher, principles of organizing information per library sciences standards are expected. A "References" section also exists as a section, because it will probably have dozens (or hundreds) of entries.

Per all of the above...

  1. Yeah, I'd like for there to be a sub-section within "How To Guides," that just isolates the two topics for which there are 3 or more articles (so, devices and clipboard).
  2. Information in small sections is often best ordered by frequency or likelihood of need, not alphabetization.
  3. No section should exist, no matter how structurally sensible, if it only has 2 articles in it. That will only make those two articles harder to find, in most circumstances.
  4. "Meeting users where they are" also anticipates their mental models when needing information. When the user of a product is reading a guide and thinks "What does that mean?" they are unlikely to also think "I'll look for a glossary in a References section." Like: would you think that when coming upon a strange term when reading the user guide for a new fridge? I don't say to shame you or make anyone feel stupid. "Glossaries" are a best practice, but not very common in consumer product user guides. So—those users need to be alerted at the outset, "Hey, a glossary exists and you don't have to play mental gymnastics to make your best guess that will also likely be wrong, hooray!"

Do we want to meet users where they're at, or do we want to force conventions upon users that they either don't expect in a consumer product user guide (the mental model many users likely are in when "just referencing the handbook" for a computer product they use on a daily basis), or have had minimal exposure to in their lives?

Two good resources to read more about IA, are below, if you feel like doing more reading. https://www.knowledgeowl.com/home/information-architecture https://www.usability.gov/what-and-why/information-architecture.html

andrewdavidwong commented 3 years ago

The only (literally) points I feel where we don't see eye to eye, I feel have to do with the "Design Principles" (or goals) the docs aspire to follow. You come from an academic background. Most humans, do not. While the Qubes user community probably has more academics in it than most Linux user communities, non-academics still comprise a healthy chunk of Qubes OS users... and, when they are using Qubes, they come into the docs with mental-models and expectations shaped by consumer product manuals and user guides. "RTFM" is a funny meme, because so often people just don't read the damn manual. Which is both my job security, and the bane of all community managers and support folks.

Information Architecture is very different from Library Science, with regards to best practices in organizing information. The prior, prioritizes human needs. The latter, prioritizes how to organize a wealth of information according to pre-defined systems that have evolved over centuries to best serve researchers and academics (people who spend their days working to make sense of thousands of books and periodicals in libraries). Neither discipline is mutually exclusive to the other, but both prioritize very different goals.

For "Technical Documentation," the prior tends to be more heavily embraced. The end-user consuming that content is also usually a technical professional being paid for their time to learn stuff to support many other people. For "Developer Documentation," standards have just kind of evolved over many years, and those standards just kind of work—mostly, because developers are by nature curious and patient individuals, and they're reading documentation because they want to know the nitty details. For "User Guides," well... every "RTFM" meme that's ever been created, explains that mess of reality.

When one is utilizing an artifact as a researcher, principles of organizing information per library sciences standards are expected. A "References" section also exists as a section, because it will probably have dozens (or hundreds) of entries.

I'm not sure what your point is here. I think I already understand this pretty well, and I don't expect users to be academics. This comes across a bit ad hominem. Seems like a lot of assumptions are being made about me conceiving of myself as an academic and trying to impose some stereotype of that worldview on others. I suggest we focus on the objective features of the work rather than the personal attributes of the person who did the work.

Yeah, I'd like for there to be a sub-section within "How To Guides," that just isolates the two topics for which there are 3 or more articles (so, devices and clipboard).

Again, please open a separate issue for this.

Information in small sections is often best ordered by frequency or likelihood of need, not alphabetization.

That is already how I have tried to organize things. ("Tried" because I don't always know what that order is.) Nothing is currently organized alphabetically (except the list of entries on the glossary page). Not sure where the notion that it is came from.

No section should exist, no matter how structurally sensible, if it only has 2 articles in it. That will only make those two articles harder to find, in most circumstances.

Ok, but your own proposal has the "Getting Started" section with only two entries...

"Meeting users where they are" also anticipates their mental models when needing information. When the user of a product is reading a guide and thinks "What does that mean?" they are unlikely to also think "I'll look for a glossary in a References section." Like: would you think that when coming upon a strange term when reading the user guide for a new fridge? I don't say to shame you or make anyone feel stupid. "Glossaries" are a best practice, but not very common in consumer product user guides. So—those users need to be alerted at the outset, "Hey, a glossary exists and you don't have to play mental gymnastics to make your best guess that will also likely be wrong, hooray!"

All the more reason to go with what I proposed above. Isn't it way easier and more natural to just be able to hover over an unfamiliar term and instantly see the definition in-context rather than have to open a completely separate page and Ctrl+F through that page for the unfamiliar term? [Edit: Opened #6761 for this.] [Edit 2: Never mind. You already opened an issue for this.]

andrewdavidwong commented 3 years ago

I think many of the general criticisms of the documentation leveled here ultimately arise because we're trying to do too many things in the documentation instead of in the software itself. The information the user needs at a given point should be presented to the user when she needs it as part of the Qubes OS interface. She shouldn't need to consult the documentation for most things. Ideally, a "mainstream" user who mostly sticks to the defaults and common workflows shouldn't need an instruction manual at all.

I feel a bit like we're leaning on the documentation as a crutch too much, and, as we've gotten used to doing so over the years, we come to blame the crutch for not holding us up well enough, when we really should be focused on the bad leg.

This isn't to say that the documentation is already perfect and doesn't need to be changed. On the contrary, it'll never be done, never be perfect, and will always need to be improved. I'm just saying, let's not miss the forest for this tree.

ninavizz commented 3 years ago

@andrewdavidwong I do not disagree with any of what you're saying above. At all.

Unfortunately, to make Qubes a "usable" and intuitive experience that users could self-guide, would take a full-time design and research TEAM (not just a few volunteers) and many developers several months (at least). If a few million dollars fell from the sky, tomorrow.

FPF is trying to get more journalists to use Qubes, now. I am trying to get more at-risk users in a place of being able to use Qubes, now. So, please know: we are both, so, totally on the same page. I'm just trying to move the mountains that I can, in lieu of other mountains requiring real developers to be moved.

andrewdavidwong commented 3 years ago

Sounds good. I'm glad we're on the same page. 🙂

It sounds like we're done with the actionable content of this issue, so I'll close it as resolved by the changes made.

ninavizz commented 3 years ago

I'm not sure what your point is here. I think I already understand this pretty well, and I don't expect users to be academics. This comes across a bit ad hominem. Seems like a lot of assumptions are being made about me conceiving of myself as an academic and trying to impose some stereotype of that worldview on others. I suggest we focus on the objective features of the work rather than the personal attributes of the person who did the work.

@andrewdavidwong In response to the above: the points I was making that you responded to, were from my understanding of Qubes as having begun as research project. Entirely unrelated to you, and entirely related to the OG userbase, contributors to, and purpose of Qubes OS. I've seen a lot of Joanna advocating for good UX, so I also am not questioning hers or Marek's interests. It's an open source project. Many of the only people with the time to invest in these things, are from academia. Many of the standards I'm observing in practice, are from academia. Entirely unrelated to you. Please understand that.

andrewdavidwong commented 3 years ago

@andrewdavidwong In response to the above: the points I was making that you responded to, were from my understanding of Qubes as having begun as research project. Entirely unrelated to you, and entirely related to the OG userbase, contributors to, and purpose of Qubes OS. I've seen a lot of Joanna advocating for good UX, so I also am not questioning hers or Marek's interests. It's an open source project. Many of the only people with the time to invest in these things, are from academia. Many of the standards I'm observing in practice, are from academia. Entirely unrelated to you. Please understand that.

Thanks for clarifying. I'm not sure if everything you're saying here is really true, but I'll leave the matter there.

ninavizz commented 3 years ago

Active and passive voice apply to sentences. I'm not sure if it makes sense to try to apply them to mere phrases. I suspect not. You've only succeeding in using active voice in (some of) these titles by converting phrases into sentences. It's not like they were in passive voice before or anything.

Andrew: The Chicago Manual of Style does not inform my guidance. What users respond to, does. This is a UX best practice for creating links in a list that are discoverable, buttons, etc. As with all best practices, context and purpose are everything—and no one best practice applies to allthethings, regardless of context.

Deeplow is also creating tutorials. Not reference material. "How To Guides" is innacurate, for reference material. Which is the entirety of this User Guide. It is not a "How To" guide. Users expect step-by-step guidance, on "How To Guides." As such, I avoid "How To Guides" like the plague, as do many users, because we just want fast answers.

ninavizz commented 3 years ago

@andrewdavidwong I also sent you some links about active voice in UX, a while back. I cannot re-share them, here, but google "Usability active voice" and you should find them. I'm sure there are infinite illogical issues to you with those best practices, but they're what have tested well with users—and that is literally all I care about with my recommendations.

andrewdavidwong commented 3 years ago

Ah, this addresses a lot of the confusion about "active voice" in UX: https://uxplanet.org/what-every-ux-writer-needs-to-know-about-passive-voice-627c0bd23b93

In the world of UX, I’ve noticed a lot of companies are adding “use the active voice” to their guidelines. Then they go on to give examples that aren’t related to the question of active vs. passive. What they mean to be saying is “use the imperative tense,” particularly on CTAs. While that’s often good practice for CTAs, it doesn’t relate to something like “Your account has been updated” vs “We updated your account.” Here, the sentence is about the account, not about some undefined “we” making the passive the better choice. Plus, the passive construction sounds much more natural and conversational here.