Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor the ORAS documentation structure and write new user guides #65

Closed
FeynmanZhou opened this issue Nov 8, 2022 · 14 comments
Closed

Comments

@FeynmanZhou
Copy link
Member

FeynmanZhou commented Nov 8, 2022

This issue relates to a proposal for a LFX mentorship project for Term 2, 2023. Please feel free to comment on this issue about your interest and willingness, but note that commenting here is not the same as applying to LFX.

  • Description: Refactor the ORAS documentation structure and write new user guides based on the latest version of ORAS.
  • Expected Outcome: Deliver a developer-friendly documentation structure for ORAS and write new user guides according to the proposed documentation structure
  • Recommended Skills: OCI, Docker, ORAS, Markdown
  • Mentor(s): Mentor(s): Terry Howe (@TerryHowe , [email protected]), Asmit Malakannawar (@asmitbm , [email protected]), Feynman Zhou (@FeynmanZhou , [email protected])

The detailed ORAS documentation structure and content should be refactored and updated to the latest version of ORAS. I would like to propose the new documentation structure as follows.

Chapters Documents Status Need to review and update existing docs? Refreshing
Overview of ORAS - What is ORAS
 - Use cases
  - Demos
  - Roadmap
2/4 Yes Per each new release. Maintained by @oras-project/oras-client-release-managers
Installation Install ORAS CLI on multiple platforms 1/1 Yes Per each new release
Getting Started ORAS CLI quick start 0   Per each new release
CLI Guides - Authentication (login and logout)
  - Pull and push artifacts  
- Attach files to artifacts  
- Copy artifacts across registries  
- Discover referrers of a manifest  
- Repository and tag operations
  - Manifest and blob operations
3/7 Yes Per each new release
How-to guides - Using ORAS in Secure Supply Chain
- Using ORAS in CI/CD (e.g. GitHub Actions)
- Working with OCI Registries
- Using ORAS with Kubernetes manifest
1/4 Yes Per each new release and E2E scenario
Development and contribution
- How to build ORAS CLI
 - Add a new command and flag
 - CLI release process
2/3 Yes Maintained by developers
Client Library - Overview
  - Golang library guide
  - API reference
  - Python library guide
  Yes Maintained by library developers
CLI Reference This part of the content will be generated from the source code of CLI help documentation. 0 No Maintained by developers and @oras-project/oras-client-release-managers
Glossary Concepts and terms 0 No Per each new term and feature
FAQ and Troubleshooting   0 No According to user questions. Maintained by @oras-project/oras-client-release-managers
@FeynmanZhou FeynmanZhou changed the title Plan to update the ORAS documentation Plan to update the ORAS documentation structure and user guides Nov 8, 2022
@TerryHowe
Copy link
Member

Screen Shot 2023-02-02 at 15 52 17

A familiar format maybe? I think some of the topics you mentioned would be subtopics of this for example troubleshooting would be in tasks.

I think the hugo migration should be first though.

@FeynmanZhou FeynmanZhou changed the title Plan to update the ORAS documentation structure and user guides Refactor the ORAS documentation structure and update user guides May 9, 2023
@FeynmanZhou FeynmanZhou changed the title Refactor the ORAS documentation structure and update user guides Refactor the ORAS documentation structure and write new user guides May 9, 2023
@Ananya2003Gupta
Copy link

I am interested in working on this issue and contributing to ORAS documentation. I have few doubts and ideas in mind, but I am unable to join the slack workspace. I have commented about the same problem in #158 (comment)
Kindly let me know, where can I communicate further for this issue.
Best,
Ananya Gupta

@Ananya2003Gupta
Copy link

Screen Shot 2023-02-02 at 15 52 17

A familiar format maybe? I think some of the topics you mentioned would be subtopics of this for example troubleshooting would be in tasks.

I think the hugo migration should be first though.

I find Meshery's Docs (docs.meshery.io) to be quite detailed and developer friendly. I feel ORAS Docs can be structured in a similar fashion with more in depth knowledge of features mentioned in the issue. The docs can be made interactive by incorporating mock up of ORAS CLI in them (if possible to do so).

@octonawish-akcodes
Copy link

I am interested in this.

@asmitbm
Copy link
Member

asmitbm commented May 11, 2023

I am interested in this.

Hi @octonawish-akcodes

You can join the Slack channel, with the provided link on the website. If that doesn't work, you can join the CNCF Slack and then navigate to the #oras channel. Say hi and introduce yourself :)

@Roseline-Bassey
Copy link

Hey, Mentors @TerryHowe , @asmitbm , @FeynmanZhou. My name is Roseline and I'm interested in contributing to this project.

@shashankiitbhu
Copy link

Hey Mentors @asmitbm @TerryHowe @FeynmanZhou . My name is Shashank Kumar and I am interested in contributing to this project.

@yash7raut
Copy link

I am interested in this.

Hi @octonawish-akcodes

You can join the Slack channel, with the provided link on the website. If that doesn't work, you can join the CNCF Slack and then navigate to the #oras channel. Say hi and introduce yourself :)

@asmitbm I am unable to join the Slack channel.

@asmitbm
Copy link
Member

asmitbm commented May 13, 2023

@asmitbm I am unable to join the Slack channel.

Hi @yash7raut,

You can use this link: https://communityinviter.com/apps/cloud-native/cncf

@yash7raut
Copy link

Thank you for the link @asmitbm.

What should be my next steps?

I am exploring the repository and trying to familiarize myself with the project.

@Vikash-8090-Yadav
Copy link

Hey Mentors @asmitbm @TerryHowe @FeynmanZhou . My name is Vikash Kumar Yadav and I am very myuch interested in contributing to this project. Can u please suggest me any first contributor issue?

@ayush4345
Copy link

Hey, can anyone tell me the deadline for applying to this mentorship?

@asmitbm
Copy link
Member

asmitbm commented May 20, 2023

Hey, can anyone tell me the deadline for applying to this mentorship?

Deadline to apply is May 23rd 5PM PDT.

@TerryHowe
Copy link
Member

Done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

10 participants