On 10/17/20 10:29 PM, icequbes1 wrote:
> Oct 17, 2020, 21:12 by j...@vt.edu
>> On Fri, Oct 16, 2020 at 9:22 PM 'icequbes1' via qubes-devel
>>> While the docs are very nice, sometimes I think there is too much documentation in Qubes that it might scare new users away.
>> I must strongly disagree.
>> ...> It's useful to understand the distinction, and what type of content is
>> appropriate for each, but having _too much_ documentation is most
>> definitely not the problem. Organization? Clarity? Staleness? Perhaps,
>> sure. Hopefully GSoD may help somewhat with that :)
> Perhaps my English could use improvement, but my intent was addressing level of detail on the documentation resources most users would reference first; not that there shouldn't be good docs for advanced users or that docs should be removed. I've got qubes-doc cloned and often grep against it.
>>> I love documentation as much as the next person, but let's hide the more scary parts that they probably will never use? Some new users think Qubes OS is overwhelming to begin with; reading esoteric commands (to a new user) in Qubes' documentation can unnecessarily add to that. My apologies if I am getting off-topic.
>> I'll leave UX decisions to the UX people, but I know you'll find
>> notable disagreement among Qubes users about the merit of this
>> approach and its suitability for Qubes. As a recent example of
>> disagreement about this philosophy, I point to
> My initial thoughts to this thread were, why not just document how to pop open the GUI updater with qubes-update-gui if one wants to update using salt. If you're not writing pillars or states or trying to script things, why not just point people to the GUI (in the documentation) and instruct users who need more control to read the man page of qubesctl (which has sufficient documentation and is authoritative).
This thread was never about primarily about documentation. Rafael simply
suggested, as a side note, documenting the information Marek provided
(which is fine and reasonable).
> I understand Qubes OS to be very thoughtful and intentional with the decisions it makes, which is good. But at times, I feel there's a bit of over-explaining to the point where less experienced linux users might feel alienated, overwhelmed, or simply find it easier to pose questions without referencing written works that already answer their question in detail. I am not diminishing anyone's documentation contributions (I've made none), but my goal was to help with appearances if I were to take on the perspective of a less experienced user. While I am familiar with linux, I have only used Qubes OS for months, so my apologies if my observations are premature.
Apparently my earlier explanations have failed, so let me try again with
an analogy: Suppose you know nothing about computer hardware. You can
use computers fine, but the internals are a mystery. What you're saying
is analogous to saying, "Computers are great, but all of these
whitepapers and articles discussing processors, motherboards, memory,
and drives are too overwhelming and intimidating for novices who just
want to do web browsing, email, word processing, and video conferencing.
They don't need to know anything about clock rates, PCIe lanes, RAM
timings, or sequential read/write speeds!
The obvious answer is: Of course they don't. These articles and other
content *aren't for them*. Those folks should just buy a suitable
computer and move on with their lives. There are others who need or want
to know details about hardware -- people whose jobs or hobbies involve
maintaining, repairing, and building computers. Surely you're not
suggesting that no content should exist for them simply because it might
scare away novice computer users.
Again, I have to point out that this is the qubes-devel mailing list. If
this sort of technical discussion isn't appropriate for qubes-devel,
then what is? Is the very *existence* of qubes-devel too alienating for
novice users? Surely not (and, even if it were, those novice users
should simply avert their eyes until the sight of qubes-devel no longer
Likewise, the documentation is split between user and developer
documentation, and the user section is further split with an "Advanced
Configuration" section. What you see as a document that "over-explains"
I see as a document targeted at a different audience (an advanced,
technical audience for whom the level of explanation is appropriate). A
single level of explanation cannot be appropriate for all audiences. The
alternative would be eliminating all but the simplest level of
explanation (literally "dumbing down" all the documentation to fit the
lowest common denominator). I can't entertain this as a serious suggestion.
There's a common theme in all this: Context matters. A thread in
qubes-devel vs. qubes-users. A doc in the user vs. dev or basic vs.
advanced section. Writing for your audience. It's all about context.