[📑 Docs]: AsyncAPI CLI Documentation

imabp commented 2 years ago

What Dev Docs changes are you proposing?

About CLI CLI helps you to work with AsyncAPI files. The following set of features are available(some are waiting to get merged and planned to be released in V1).

new --template
validate
diff
convert
start studio
new
generate
bundle
optimize

Documentation

We currently do not have any documentation on front-end for the user to know the available set of commands and examples showcasing, their usage. This issue tries to resolve the same.

It will be nice to have a document for CLI at this page https://www.asyncapi.com/tools/cli

Documentation Structure This is an example documentation structure showcasing new validate and diff commands.

AsyncAPI Example Specification
Commands Usage
- new
  - 50-60 words description
  - usage
  - flags
    - with template
    - no template
- validate
  - 50-60 words description
  - usage of validate command
  - example output when validate is successful, or failed.
  - flags
    - watch
- diff
  - 50-60 words description
  - usage
  - example output
  - flags

Accountability and Notes

I can work on this and probably based on, if we are in, it can be a part of Season Of Docs. Project Board: https://github.com/orgs/asyncapi/projects/8

Code of Conduct

[X] I agree to follow this project's Code of Conduct

quetzalliwrites commented 2 years ago

Hey there @imabp, thank you for your OSS submission and interest and contribution! I def want to work with you on this, and even regardless of Google Season of Docs 2022, if only in case they don't select us 😄😂👍🏽🙊 (I am submitting to them for us, no worries!)

Let me share where in the Docs this would be great to start adding. 😀

Take a look at #350 and #503 please 🙏🏽 ✌🏽, because those Docs issues detail and include Figma designs by @mcturco for upcoming changing to the HomePage of our current Docs.
If you take a look at our current "homepage" for entering our Docs, you will see the URL is as follows: asyncapi.com/docs/getting-started. We will be changing that and we're in the process of creating a NEW HomePage for our Docs. (as detailed in point 1 where it mentions issues #350 and #503)
As you can see from our current plan, your awesome ✨CLI✨ contribution would go under the new Information Architecture under the Reference section, with the URL being: asyncapi.com/docs/reference/cli.

Let me know if that makes sense or what questions/thoughts 💭 you may have. 😄👍🏽👍🏽

imabp commented 2 years ago

Thank you for following up on this. @alequetzalli This is really nice way 😊, we can go forward.

Also, we are adding more features for CLI, so I am just waiting for few PRs to get merged, and then generating the doc out of it. 😄

quetzalliwrites commented 2 years ago

That sounds great @imabp, looking forward to seeing the new CLI features and your upcoming doc PR ✨✨

Souvikns commented 2 years ago

🤩 Wow love the new design for docs.

In terms of CLI, I have one small doubt -

Workflow/pipeline for new documentation

CLI still hasn't reached v1 yet so many new features are added and changed on regular basis, for this we thought of using tools like https://openbase.com/js/oclif/documentation#oclif-readme to generate documentation but it looks something like this https://github.com/asyncapi/cli/issues/123#issuecomment-1025185164 which is probably not that intuitive.

If we have manual docs on the website how are we going to keep up with the changes in the CLI and if we are going to generate the documentation with some tool, how are we going to sync it up with CLI repo to the website repo.

quetzalliwrites commented 2 years ago

@Souvikns The workflow will be the same for all docs. It is put in a PR, goes through a review process, and eventually when approved gets merged.

We do not have tools for generating docs yet, but even when we do add them, we will be going through a Technical Writing review, we are not going to copy/paste random stuff from READMEs :)

imabp commented 2 years ago

@Souvikns , as some features have been decided for V1, I will start documenting them. Hope that's fine CC: @alequetzalli

derberg commented 2 years ago

my 5 cents: just let us remember folks, in the case of CLI, we should generate docs from code as much as possible. We already know that sometimes in CLI we even forget updating the Readme, so updating main docs will be even more complicated. So better to generate them. Just making sure you remember 😄

quetzalliwrites commented 2 years ago

@derberg that sounds good to me, do I need to sync w/ you or someone else about how the coding side of generating them can be done? I think we still need to identify a contributor for that, right? 🤔 💭

Or are you also working on that, @imabp?

P.S. @imabp let me know if you need more guidance on getting the CLI Docs PR started, I have more folks tagging me lately in Docs so I want to make sure I don't leave you forgotten 🤣 ❤️

I am also now going to greatly update this issue so that I can provide more guidance and help make this a good-first-issue for the community to pick up. I will also share this issue again in our Docs slack channels to see if there are more folks interested in helping with this one.

Souvikns commented 2 years ago

@derberg that sounds good to me, do I need to sync w/ you or someone else about how the coding side of generating them can be done? I think we still need to identify a contributor for that, right? 🤔 💭

I can help with this @alequetzalli.

imabp commented 2 years ago

Hey @alequetzalli , I am taking up this thing. But I can not do it alone, as it needs some inputs from @Souvikns as well. Earlier, things were in development, and unstable, but now we are bit stable, so can we start working on it @Souvikns @derberg ?

Souvikns commented 2 years ago

I have some doubts about where should we keep our documentation, should it be in the website repo or the CLI repo.

If we are using CLI repo we could generate with a tool and the website could somehow fetch it from there and render it.
If we are keeping the documentation in the website repo we have to open two PRs in two different repositories to make any changes.
- maybe we can have a workflow that runs when we push to CLI. It would generate documentation and then open PR on the website repo.

One more thing, Also with usage docs, maybe we could have some kind of developer docs that would make it easy for new developers wanting to contribute to CLI to understand the codebase faster.

@alequetzalli we had this going on for CLI's documentation generation https://github.com/asyncapi/cli/issues/123#issuecomment-1025185164 can you tell me that is this generated document good enough.

@derberg @alequetzalli @imabp let me know your thoughts on what we should do.

derberg commented 2 years ago

by principle, technical docs belong to the repo where the code is. So docs are updated in the same PR that code is updated.

so we write/generate docs incli and then push it to website, just like we push for example specification from spec to `website

and yes, we should have decent dev docs for contributors to ease contribution.

quetzalliwrites commented 2 years ago

I have some doubts about where should we keep our documentation, should it be in the website repo or the CLI repo.

@Souvikns As @derberg explained, we will write/generate the initial README docs in the cli repo and create a tool that pushes them into website too, or rather.. generates a PR to the website repo too.

That said, that PR from repo READMEs to website Docs will undergo a thorough review before it gets approved/merged into the website's main Docs.

@alequetzalli we had this going on for CLI's documentation generation asyncapi/cli#123 (comment) can you tell me that is this generated document good enough.

This is useful and can/should be added to our website's main Docs, but again, this is not ready to be pushed LIVE to our Docs. This is rough and needs to go through PR review. 😄

@Souvikns let me know if that makes sense !

quetzalliwrites commented 2 years ago

Hey @alequetzalli , I am taking up this thing. But I can not do it alone, as it needs some inputs from @Souvikns as well. Earlier, things were in development, and unstable, but now we are bit stable, so can we start working on it @Souvikns @derberg ?

Hey @imabp, that's a great follow-up question! Thank you for noting and remembering that we were making some key changes to the Docs Information Architecture first...

The current update is here in my Gist that I just wrote: https://gist.github.com/alequetzalli/dd63a0e688735c4ab95e28457318d6b1#-what-main-change-is-happening-in-the-docs

As you can see, that PR #601 is still in dev/design/writing stage so we are SOOOO close to being able to start adding docs that are generated.

I think we are very close to closing that PR, it seems to be mostly done.. and I will keep you in the loop!

Essentially, for now start planning for CLI docs to go under: asyncapi.com/docs/reference/cli

I think that is enough to start creating your tool to generate the docs and migrate them to website repo? I assume you are creating a tool that pushes them into the website repo too, or rather.. generates a PR to the website repo too.

That said, that PR from repo READMEs to website Docs will undergo a thorough review before it gets approved/merged into the website's main Docs.

Let me know if this makes sense and what you think 💭 😸

imabp commented 2 years ago

This works really well 😁. On it @alequetzalli

icode247 commented 2 years ago

Hi @alequetzalli I am Ekekenta Odionyenfe Clinton. I am a software engineer and a technical writer with 3 years of experience. I have authored for companies like Logrockets, OpenReplay, Loginradius, Arctype, Fauna, etc.

I love to contribute to AsyncAPI to create the AsyncAPI CLI documentation.

imabp commented 2 years ago

Hello @icode247 , I am actually working on this locally. There are other many issues that needs a care. Please do take a look at them.

quetzalliwrites commented 2 years ago

@icode247 Like Abir noted, this issue is already assigned :)

imabp commented 2 years ago

So I was brainstorming about this. And need some answers to these two questions

TLDR; Move CLI from reference to tools. Propose get started and api reference docs under CLI in the asyncapi docs Propose workflow for the above docs. Inputs from the reviewers and codeowners.

@alequetzalli, as CLI is a tool, so can we move it under tool instead of reference ?
@derberg , @Souvikns now the thing, is, I was looking at various kinds of docs published by companies like Netlify, Docker, etc.
- What I realised is this?
  - Docs should be friendly for first time users
  - Docs should be easily readable for developers for the reference.
Problem
- Now the problem is generating docs from code, will definitely make it useful for developers who are just using it as a reference and already using AsyncAPI CLI. But, to onboard the new comers, those who just want to get started with CLI, the docs should be more in user friendly tone and hand crafted so one can easily get started.
Proposed Solution
- Seeing different kind of docs, I really liked how Netlify CLI docs tries to solve both the problems. And I would like to propose a similar solution for AsyncAPI CLI.
- Screenshot
- API Reference will be generated by using oclif readme
- Get Started docs will be hand written by me and approved by @alequetzalli @Souvikns and other codeowners(if any).
This makes sure, we need not edit the API Reference manually, instead depend on oclif readme to generate it. Only thing that we will update, is Get Started with CLI,
Workflow
- Create a Get Started Docs using .mdx
- Write a workflow to generate API reference for every release in CLI.
- Improve the code style, if there is any clarity required in API References and regenerate the API Reference.
- Github Workflow to create a PR in the website repository, with API reference for current release of CLI.

✨ Now I need to know inputs from @alequetzalli @magicmatatjahu @Souvikns @derberg, about all this and how you feel about it ?

quetzalliwrites commented 2 years ago

@imabp

(1)

Hey, thanks for asking but we do not want CLI under tools. I an placing anything related to console, dev env, and API spec under Reference 😄

Please go ahead as we already planned so that your awesome ✨CLI✨ contribution would go under the new Information Architecture under the Reference section, with the URL being: asyncapi.com/docs/reference/cli.

(2) So I like where you're mind is going but this is the outline I'm going for when you add your docs to the PR:

Reference
     CLI
          Installation
          Commands

Good question about the code owners, the way it works for Docs in the /website repo, is that I'm automatically a reviewer and owner of all .md files and then the contributor who owns the code on each repo can get manually added.

But if you're editing documentation files in other repoes (example: the /spec repo that automatically updates the Docs in the /website repo when a PR is merged)... then the code owners of those files get added automatically.

imabp commented 2 years ago

Thanks @alequetzalli Here is how the reference bar, we would like to have.

Reference
   - CLI 
       - Get Started
       - Command Reference

Get Started Page - will be typed manually.
Command Reference - will be generated from release code.

@Souvikns and @derberg , need your reviews.

quetzalliwrites commented 2 years ago

Thanks @alequetzalli Here is how the reference bar, we would like to have.
Reference
   - CLI 
       - Get Started
       - Command Reference

@imabp Hmmm... I am still thinking about using "Get started" because I like that "installation" is to the point. But if you want to try that, then I want you to change it to Getting Started because consistency across Docs is key. (We use the term 'getting started' in Tutorials, so let's match that.)

Get Started Page - will be typed manually.

Command Reference - will be generated from release code.

Yes, this looks right. But 2 Command Reference, also needs to generate a PR to be reviewed. I run into too many spelling and grammar issues, so we must have that reviewed always before added to the website Docs.

imabp commented 2 years ago

Yes,Getting Started sounds better

Reference
   - CLI 
        - Getting Started
        - Command reference

Regarding the following @alequetzalli

Command Reference - will be automatically generated from release code.

Yes though its generated by a bot, you can still review it for the grammatical mistakes before merging the PR 😄

quetzalliwrites commented 2 years ago

@imabp Thanks for clarifying that both ways generate a PR first; that's what I needed to make sure. Sounds great! 👍🏻

Souvikns commented 2 years ago

@alequetzalli I have a question, where should @imabp open the PR, in the CLI repo or the website repo. I personally think it should be in the CLI repo just like spec and then we can sync it using a GitHub action much like spec repo does. We can add you as a code owner in the CLI repo for review purposes.

Let me know what you(@alequetzalli) and @derberg decide on this.

imabp commented 2 years ago

@Souvikns

As you see above the structure.

Reference
   - CLI 
        - Getting Started
        - Command reference

The Getting Started will be manually written, and PR will be raised in Website repo.
The Command Reference will be generated in CLI itself and PR will be raised by the Github Action

derberg commented 2 years ago

All docs work for CLI should be done in the CLI repo. Getting started too.
We do need docs other than Installation and Command reference because we need to explain some things, like the concept of context and why it is needed. Even a simple tutorial on what the suggested workflow looks like is needed. Even cheat sheet for most cool commands, like command to quickly generate asyncapi file from a template or command to open studio or command to validate with watcher
I'm not 100% sure Reference is a place for CLI because, it is not just reference and it will be always confusing for devs that all tools are under tools but CLI is not....but in general, I'm not much worried about it now, as changing location is the easiest. Let's get content first 😄

quetzalliwrites commented 2 years ago

@imabp @derberg Rejoice 🥳🥳🥳, I am changing my vote to put CLI into the Tools content bucket.

New url: Asyncapi.com/docs/tools/cli

New outline to start:

cli/getting-started
cli/commands

imabp commented 2 years ago

Finally, its a victory 🤭....for both of us ✨ CLI is going under tools!!

Awesome, Thanks again @alequetzalli for approving this

imabp commented 2 years ago

@Souvikns we can continue on the CLI command reference using the tool mentioned in asyncapi/cli#123

And I will be writing the getting started document

github-actions[bot] commented 2 years ago

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

derberg commented 2 years ago

still valid

imabp commented 2 years ago

@derberg i wish, if we could assign priorities here...This is of lower priority, as more features are being developed in CLI.

github-actions[bot] commented 1 year ago

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

asyncapi / website