Initial Documentation #32
Conversation
31fe1b9 to
5232617
Compare
There was a problem hiding this comment.
Thank you! This looks nice, some suggestions inline.
There is some overlap with the existing README, I guess we can shorten the README in the future but I do feel like the README should keep a quick-start like section that gives the user an image in the first few lines (to avoid that we lose our audience to quickly if they need to click on another link).
It might be nice to go into "--output=json" here as well as this is something that we probably do not need in the overview README
And one more comment: I personally would squash the commits.
|
One more idea - maybe worth documenting how to override the "repositories". This is currently possible via "--datadir" but nowdays we could just provide a "--repositories-dir" (or similar) argument as we now control what dirs to look into (before reporegistry was used that hardcodes "repostiroes/ into the dirname) |
|
Also needs mention of the recently landed |
There was a problem hiding this comment.
I love this, thanks! ❤️
I have some thoughts about the structure. Having "installation" as the first step feels quite heavyweight to end-users. They just want to use the software, not care about installing. Also, installation doesn't make much sense when we provide a container image.
Thus, I suggest making 3 sections:
-
Quick start.
Make it very opinionated, so people always succeed. Ask just one question. Are you running Fedora? Use the RPM way. Use anything else? Use the container.
Make it 3 steps: prepare (either RPM install, or mkdir output), run (build a minimal-raw), validate (a quick qemu command to verify that the image actually works).
Make sure that when I copy all commands into my terminal, it just works. -
Installation
This is the place to mention COPR and installation from source. Also, you can mention that we tag the container images with git shas here, that's pretty cool. As I mentioned inline, I would drop the Go method, it doesn't provide any benefits over cloning the repository imo. -
Usage
The same as you already have.
aa6c2c6 to
8c7cddf
Compare
|
I have gone through all the comments and resolved all (I hope). Please give it a read again. |
Supply initial documentation for `image-builder`. This documentation will be imported into the osbuild [1] website. [1]: https://osbuild.org/ Signed-off-by: Simon de Vlieger <supakeen@redhat.com>
There was a problem hiding this comment.
This looks like a fine starting point to me, I put some comments inline but given the dynamic nature of the projects starting small and expanding as we go (e.g. optios for controlling progress, output dir, list of support options etc).
Maybe someone else also wants to also have a look though, docs are not my strong suite :)
Let's have some tiny initial docs; to be expanded later.