Re: [edk2-devel] [PATCH v1 2/6] ArmVirtPkg: Add Platform CI and configuration for Core CI

["Rebecca Cran" <rebecca@bsdio.com>]

> -----Original Message-----
> From: Laszlo Ersek <lersek@redhat.com>
> Sent: Thursday, April 16, 2020 7:52 AM
> To: Sean Brogan <sean.brogan@microsoft.com>
> Cc: devel@edk2.groups.io; Ard Biesheuvel <ard.biesheuvel@linaro.org>
> 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&amp;data=02%7C01%7Csean.brogan%40microsoft.com%7Cd94de877b9e74e06f08208d7e215bca4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637226455298322408&amp;sdata=afDNhjdLt%2B9G4idYYGARh0RiTUnxCBx4fyBA5xT8k9Q%3D&amp;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&amp;data=02%7C01%7Csean.brogan%40microsoft.com%7Cd94de877b9e74e06f08208d7e215bca4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637226455298322408&amp;sdata=nUtyttk3BdcGKyTepkUy0OnILT7%2FcBnHCMyt5eAO%2BG8%3D&amp;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