From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from out02.mta.xmission.com (out02.mta.xmission.com [166.70.13.232]) by mx.groups.io with SMTP id smtpd.web12.6411.1587329809205594380 for ; Sun, 19 Apr 2020 13:56:49 -0700 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: bsdio.com, ip: 166.70.13.232, mailfrom: rebecca@bsdio.com) Received: from in02.mta.xmission.com ([166.70.13.52]) by out02.mta.xmission.com with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jQGze-0008Oi-Kf; Sun, 19 Apr 2020 14:56:46 -0600 Received: from mta4.zcs.xmission.com ([166.70.13.68]) by in02.mta.xmission.com with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.87) (envelope-from ) id 1jQGzd-0000Mc-TQ; Sun, 19 Apr 2020 14:56:46 -0600 Received: from localhost (localhost [127.0.0.1]) by mta4.zcs.xmission.com (Postfix) with ESMTP id AA54E5005C1; Sun, 19 Apr 2020 14:56:45 -0600 (MDT) X-Amavis-Modified: Mail body modified (using disclaimer) - mta4.zcs.xmission.com Received: from mta4.zcs.xmission.com ([127.0.0.1]) by localhost (mta4.zcs.xmission.com [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id 7lDiMXY5xYe7; Sun, 19 Apr 2020 14:56:45 -0600 (MDT) Received: from [10.0.10.120] (c-174-52-16-57.hsd1.ut.comcast.net [174.52.16.57]) by mta4.zcs.xmission.com (Postfix) with ESMTPSA id 5982750038F; Sun, 19 Apr 2020 14:56:45 -0600 (MDT) To: devel@edk2.groups.io, sean.brogan@microsoft.com, Laszlo Ersek Cc: Ard Biesheuvel , "Kinney, Michael D" References: From: "Rebecca Cran" Message-ID: Date: Sun, 19 Apr 2020 14:56:44 -0600 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 MIME-Version: 1.0 In-Reply-To: X-XM-SPF: eid=1jQGzd-0000Mc-TQ;;;mid=;;;hst=in02.mta.xmission.com;;;ip=166.70.13.68;;;frm=rebecca@bsdio.com;;;spf=pass X-SA-Exim-Connect-IP: 166.70.13.68 X-SA-Exim-Mail-From: rebecca@bsdio.com X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on sa08.xmission.com X-Spam-Level: * X-Spam-Status: No, score=1.3 required=8.0 tests=ALL_TRUSTED,BAYES_50, DCC_CHECK_NEGATIVE,T_TM2_M_HEADER_IN_MSG,T_TooManySym_01,TooManyTo_001, TooManyTo_002,XMSubLong,XM_B_Unicode autolearn=disabled version=3.4.2 X-Spam-Report: * -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP * 0.8 BAYES_50 BODY: Bayes spam probability is 40 to 60% * [score: 0.4967] * 0.7 XMSubLong Long Subject * 0.5 TooManyTo_002 Multiple "To" Header Recipients 3x (uncommon) * 0.3 TooManyTo_001 Multiple "To" Header Recipients 2x (uncommon) * 0.0 XM_B_Unicode BODY: Testing for specific types of unicode * 0.0 T_TM2_M_HEADER_IN_MSG BODY: No description available. * -0.0 DCC_CHECK_NEGATIVE Not listed in DCC * [sa08 1397; IP=ok Body=1 Fuz1=1] [Fuz2=1] * 0.0 T_TooManySym_01 4+ unique symbols in subject X-Spam-DCC: XMission; sa08 1397; IP=ok Body=1 Fuz1=1 Fuz2=1 X-Spam-Combo: *;devel@edk2.groups.io, sean.brogan@microsoft.com, Laszlo Ersek X-Spam-Relay-Country: X-Spam-Timing: total 445 ms - load_scoreonly_sql: 0.06 (0.0%), signal_user_changed: 15 (3.4%), b_tie_ro: 13 (2.9%), parse: 1.30 (0.3%), extract_message_metadata: 19 (4.2%), get_uri_detail_list: 3.8 (0.9%), tests_pri_-1000: 9 (1.9%), tests_pri_-950: 1.35 (0.3%), tests_pri_-900: 1.13 (0.3%), tests_pri_-90: 80 (18.0%), check_bayes: 78 (17.5%), b_tokenize: 8 (1.7%), b_tok_get_all: 12 (2.8%), b_comp_prob: 4.7 (1.1%), b_tok_touch_all: 48 (10.8%), b_finish: 1.32 (0.3%), tests_pri_0: 306 (68.7%), check_dkim_signature: 0.50 (0.1%), check_dkim_adsp: 82 (18.4%), poll_dns_idle: 80 (17.9%), tests_pri_10: 2.5 (0.6%), tests_pri_500: 7 (1.6%), rewrite_mail: 0.00 (0.0%) Subject: Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI X-Spam-Flag: No X-SA-Exim-Version: 4.2.1 (built Thu, 05 May 2016 13:38:54 -0600) X-SA-Exim-Scanned: Yes (on in02.mta.xmission.com) Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit Content-Language: en-US > -----Original Message----- > From: Laszlo Ersek > Sent: Thursday, April 16, 2020 7:52 AM > To: Sean Brogan > Cc: devel@edk2.groups.io; Ard Biesheuvel > Subject: [EXTERNAL] Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI > > > My excuse for not polishing it more -- which I honestly do believe is a > *valid* excuse -- is that users have shown repeatedly that they don't read the README at all. I've explained basic stuff like "how to capture OVMF's debug log" umpteen times on the list, despite it being spelled out in the README. The fact is that effort put towards careful documentation is almost entirely lost effort -- this was also clearly proved by the (non-)reaction that I got to my OVMF white paper that I wrote a few years back (~60 A4 pages, if I recall correctly). > > Documentation is just not *worth* polishing, considering the user base as a whole. I for one go to the available documentation *before* starting to use new software, or when questions pop up, but it seems like I belong to a vanishingly small camp with that. People just flock to social media (or, in the least wrong case: they come to this mailing list), and ask questions they could already find the answers to in existent documentation. > > This is a bitter realization for me, especially having written relatively substantial articles for the edk2 wiki: > > https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Ftianocore%2Ftianocore.github.io%2Fwiki%2FLaszlo%27s-unkempt-git-guide-for-edk2-contributors-and-maintainers&data=02%7C01%7Csean.brogan%40microsoft.com%7Cd94de877b9e74e06f08208d7e215bca4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637226455298322408&sdata=afDNhjdLt%2B9G4idYYGARh0RiTUnxCBx4fyBA5xT8k9Q%3D&reserved=0 > https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Ftianocore%2Ftianocore.github.io%2Fwiki%2FTesting-SMM-with-QEMU%2C-KVM-and-libvirt&data=02%7C01%7Csean.brogan%40microsoft.com%7Cd94de877b9e74e06f08208d7e215bca4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637226455298322408&sdata=nUtyttk3BdcGKyTepkUy0OnILT7%2FcBnHCMyt5eAO%2BG8%3D&reserved=0 > > but it is what I now believe. Where are those pages linked from (i.e. how would people find them)? The Github wiki just confuses me: I don't see how it's useful for a project as large/complex as TianoCore. Compare it to https://wiki.freebsd.org/, where there's a large table of contents right on the front page.  And then clicking on 'UEFI', you go to https://wiki.freebsd.org/UEFI where there's another table of contents - and has the breadcrumb navigation. It feels much easier to use to me at least. And having looked through the OVMF README file in the past, I recall it being pretty difficult to find information in. It's a little long, and with it all being plain text it's not very easy to navigate. -- Rebecca Cran