doc: massive overhaul of documentation #1264
Conversation
phip1611
force-pushed
the
doc
branch
2 times, most recently
from
5d2c998 to
8a4a40a
Compare
|
I'm broadly on board with these changes, but I'm having a little difficulty reviewing it all as one PR -- quite a bit of stuff is changing which makes it hard for me to feel confident I'm seeing all the details. Could we break some of this out into separate PRs, e.g. one PR to drop the out-of-date (Small CLs is a summary I find helpful of why small changes can help reviews.) |
Copy that, sorry. I'm usually totally on your side, but this time I was just a little too lazy. 🫣 🤣
I don't think that multiple PRs help to transport the main idea and the higher objective of my changes. But I separated everything into multiple logical commits - I hope this improves the review-ability.. does it help? I think the changes made here are a major improvement. As my boss always says: Do nice things and talk about it. |
phip1611
force-pushed
the
doc
branch
13 times, most recently
from
0af5eea to
450bb33
Compare
The main idea here is to: - tell that `uefi` is not only for EFI images but also apps that interact with UEFI functionality, such as parsing a memory map from a pre-defined chunk of memory. - streamline the doc
This prepares what the following commits will provide.
This is the beginning of moving all relevant information from README.md to lib.rs. The main idea is to have `lib.rs` as main entry point into the documentation instead of an inconsistent mixture between the README and the lib.rs file.
phip1611
force-pushed
the
doc
branch
4 times, most recently
from
c44e0ea to
903db8f
Compare
Copy MSRV, License, and Contributing sections to lib.rs and streamline it with the README equivalents. We should also include these information in lib.rs, as it is the main entry point into everything relevant about the library. At least, it should from now on. The big benefit is that the documentation on `docs.rs` then covers everything relevant.
The About section is a more comprehensive write-up of the TL;DR section mentioned earlier. It should guide the user to know what they can do with this lib.
This is especially interesting as the `std` implementation of Rust is upcoming
…Resources" This is logically following the About section.
Also added "UEFI Strings" subsection
Now, the README are the entry into the repository and guide the user to the actual documentation in lib.rs respectively on docs.rs.
Yep, the multiple commits do help, thanks. I still think Github's UI for reviewing individual commits is not very good, so where possible I do prefer for parts to be pulled out to separate PRs when possible (in this case I think it wouldn't detract from anything to pull the |
| [](https://crates.io/crates/uefi) | ||
| [](https://docs.rs/uefi) | ||
|  | ||
|  | ||
|  | ||
|
|
||
| ## TL;DR |
There was a problem hiding this comment.
nit: I think we should drop the tl;dr header here since the section is just one sentence. Have this content come directly after the "Rusty wrapper for the Unified Extensible Firmware Interface." sentence.
| [](https://crates.io/crates/uefi) | ||
| [](https://docs.rs/uefi) | ||
|  | ||
|  | ||
|  | ||
|
|
||
| ## TL;DR | ||
|
|
||
| Develop Rust software that leverages **safe**, **convenient**, and |
There was a problem hiding this comment.
nit: For clarity I would add a few words at the start of the sentence like "This crate makes it easy to develop Rust software [..].". Makes it clearer that we aren't necessarily the ones making the safe/convenient/performant software, but rather we're helping users of the crate do that.
| @@ -12,6 +12,13 @@ | |||
| //! Feel free to file bug reports and questions in our [issue tracker], and [PR | |||
| //! contributions][contributing] are also welcome! | |||
| //! | |||
| //! # About this Document | |||
There was a problem hiding this comment.
IMO this section isn't needed. Having some description at the front of a multi-page document can be helpful, but here it's pretty clear what all the content is by just scanning through the following sections on the page.
| //! disks or the network. EFI images, the files that can be loaded by an UEFI | ||
| //! environment, can leverage these abstractions to extend the functionality in | ||
| //! form of additional drivers, OS-specific bootloaders, or any different kind | ||
| //! of low-level applications (such as an [IRC client][uefirc]). |
There was a problem hiding this comment.
The IRC client is a neat project, but I'm not sure it makes sense to mention in the readme since it's a pretty niche use case, unlike drivers and bootloaders.
|
|
||
| ## MSRV | ||
| With `uefi`, you have the flexibility to integrate selected types and | ||
| abstractions into your project or to conveniently create EFI images, addressing |
There was a problem hiding this comment.
nit: Here and elsewhere, let's standardize on always saying UEFI instead of EFI. I've heard people mention confusion around this on a few occasions, since it's not obvious without some research that we mean the same thing when we say EFI and UEFI.
| //! create EFI images. | ||
| //! | ||
| //! We will closely monitor the situation and update the documentation | ||
| //! accordingly, once the `std` implementation is more mature. |
There was a problem hiding this comment.
IMO we should not pass a judgement here on whether it's mature (parts are perfectly usable, parts are still in development, and it really just depends on what you need out of it).
I would drop everything from "that is yet far from being mature" on. Instead, just give the facts: explain that it allows you to write UEFI programs that look very similar to normal programs running on top of an OS, and also mention that it is still under development (without promising that we'll closely monitor it, since I think that monitoring is better done by potential users of it)
| //! We will closely monitor the situation and update the documentation | ||
| //! accordingly, once the `std` implementation is more mature. | ||
| //! | ||
| //! ## `r-efi` |
|
Could you please drop a word or two on whether you think the overall changes are beneficial and a clear improvement? Do you support that lib.rs/docs.rs should be the main documentation entry into the project? |
|
Yes, I think removing some of the duplication, having a fairly minimal readme, and having I also think there's a balance to be struck with documentation; it's OK to have some amount of duplication (https://docs.divio.com/documentation-system/structure/#the-tendency-to-collapse is a good doc on this). But I think the intent of our readme and |
|
Split-out 1/N is live: #1284 |
doc: reorganize
This is a massive re-organization of the existing documentation. The main goal
is to streamline what is provided in the README.md and what is in the lib.rs file.
I think, we need to answer some more questions and to redistribute
these answers to where users most naturally expect documentation. When in doubt,
lib.rs should be preferred and the README should forward to docs.rs.
This resolves also many inconsistencies along the way, remove (IMHO) unnecessary
pieces, and adds relevant (but yet missing) information.
Checklist