Improve Documentation with real world use-cases and additional information

[dirsigler]

Hello everyone,

I've recently seen an increasing interest and advertisement around the ORAS project.
While digging through some possible use cases and the documentation, I found that amy of the examples just contain something like:

"We create some text file and attach it to the image".
While this is technically correct, I don't assume this is a valid use case for most interested people.

Here I would recommend that maybe additional "deep-dive" documentation is added. For example how an SBOM is attached to the image and pushed.

Furthermore while looking at the documentation, the flag --artifact-type is specified which is required to specify the type of the attached object, but little to no documentation exists on the valid artifact types.
The --help docs just state:

--artifact-type string artifact type

Would recommend we add some information on how these artifact types can be construced.

I assume this would help other Engineers to pick up possible use cases for this tool and adopt it quickly into their environment.

What do you think?

[FeynmanZhou]

Hi @dirsigler ,

Thanks for the feedback. I agree with you that the ORAS user doc is a bit technical. We need to improve from the real world scenarios perspective.

Are you refering the docs on oras.land?

We will transfer this discussion into a GitHub issue and move it to ORAS-WWW repo.

[FeynmanZhou]

Related issue: oras-project/oras-www#474

[dirsigler]

Hey, yes the docs on oras.land.
For example here: https://oras.land/docs/commands/oras_attach