Cli-microsoft365: Enhancement: Add link to the documentation site from the README file

[sebastienlevert]

Description

As of today, it's really hard to get to the documentation site from the README file.

Expected result

In the getting started, we should be able to click on a link that gets us to the documentation site for any "first timer" that know nothing about the documentation site and / or the CLI for Microsoft 365

Actual result

We are redirected to the md files in the repo but the result is WAY better on the MKDOCS site!

[waldekmastykarz]

Our reasoning was, that since you arrived in the repo, we want to keep you in the repo, rather than redirecting you to an external location. The repo and readme is targeted at contributors while the docs are meant primarily for the users. When you are in the repo, you can navigate to the docs using the link in the about section in the top-right part of the page.

[sebastienlevert]

I understand, but there are areas that, as it's built for mkdocs, are not necessarily well display in GitHub (embeds, admonitions (!!!) and other examples). Also as a "consumer" of the docs, I rather prefer the "real" version of the docs to help me in my job. Without that link it's actually impossible to "know" that there is a CLI documentation site, except by Googling...

I love how the other PnP projects offer this as it allows me to decide how to consume the docs!

[waldekmastykarz]

If you're interested in the CLI as a tool to use (not to contribute), how did you arrive to the GitHub repo? Was is the first link that you got in the search results? If so, what was your search term? Just trying to understand the use case 🙂

[sebastienlevert]

Might be that I'm a mix of both users! Google does reference the Docs site as the first link. But if you "start" with GitHub, though, you don't have a link to the docs site, whereas you have a link to GitHub from the Docs site...

I would simply expect to have both links available on both sources! Maybe more of a personal opinion, I guess.

[waldekmastykarz]

Just to check: this is where we have the link at the moment, which is the default about section of the repo:

It's the same on any repo on GitHub so we wanted to stay consistent 😊

With that said, if that location is not intuitive, then we should consider adding a link to the docs in README.

@pnp/cli-for-microsoft-365-maintainers any opinion?

[garrytrinder]

I have started some work on a refreshing the readme which is available from the below branch, it needs some work but I think the issue that @sebastienlevert raises.

https://github.com/garrytrinder/cli-microsoft365/tree/readme-refresh

You can see I have added a website link near the top of the page with other links to jump to other parts of the readme, as it's near the logo and other information I think it's more noticeable as I think the behaviour of most people is to just scroll down to the readme and it's easy to scroll the website link on the right hand side off the page and not notice it until you scroll back up.

[waldekmastykarz]

Awesome! Ship it! 🚀

[sebastienlevert]

I love it! Great work! Way better than my stuff 🤣

[garrytrinder]

Let me make the final changes over the weekend.

There are a few things I want to add & change, as well as recording a new video of the CLI.

[arjunumenon]

Hey @garrytrinder - Just now noticed the change in Readme. Wow... Amazing.. Loved the way how it is organized well with all the information... What I loved are the links which are there in top which will take the users to any of the needed sites.

Great thought process and design.. 👏👏👏👏

[garrytrinder]

Thank you @arjunumenon ❤️

I'd love to take all the credit but a lot of the inspiration came from the readme of spaceship-prompt project that I use as my shell and which I love the layout of 😊