-----Original Message-----
From: Laszlo Ersek <ler...@redhat.com>
Sent: Thursday, April 16, 2020 7:52 AM
To: Sean Brogan <sean.bro...@microsoft.com>
Cc: devel@edk2.groups.io; Ard Biesheuvel <ard.biesheu...@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&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
-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#57579): https://edk2.groups.io/g/devel/message/57579
Mute This Topic: https://groups.io/mt/72880537/21656
Group Owner: devel+ow...@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com]
-=-=-=-=-=-=-=-=-=-=-=-
