Awesome work @Jwaegebaert . We will review it ASAP 🤩

@garrytrinder, I believe you had some ideas in this space. Would you mind reviewing this PR?

Great work @Jwaegebaert 👏

I've had a quick look and here are some of my initial thoughts.

• Consider changing the Contributing landing page to provide an overview and index of the pages under this section, the current page doesn't help guide me to my next step. An index helps provide an end to end view of the guide as you can see all the steps within that guide.
• Consider providing two routes to tutorials on the landing page, one for contributing a new command and the other a sample script. Each route has a potentially different audience, some folks just want to contribute scripts, so may focus on this first.
• Consider using a different command name or example that doesn't currently exist i.e. foo command. The group get command already exists, so should we consider using something different to avoid conflicts.
• Consider including numbers in the headings to make it clear that the steps are to be followed in order.
• Consider that the guide should focus on instructing the reader to perform actions and see immediate results to those actions. We should be very much handholding them through the process for creating a command or a script. Currently I don't feel that we do this and leave things to interpretation. Let's make sure they are setup and ready like having npm watch running.

Great pointers @garrytrinder! I've got a few questions.

Consider providing two routes to tutorials on the landing page, one for contributing a new command and the other a sample script. Each route has a potentially different audience, some folks just want to contribute scripts, so may focus on this first.

Do you maybe know how we can achieve this with Material for MkDocs? I'm asking this because I had the same thought but didn't find a proper way of visually implementing this.

Consider using a different command name or example that doesn't currently exist i.e. foo command. The group get command already exists, so should we consider using something different to avoid conflicts.

This was my initial thought also, but won't it be easier for users to have a fully implemented example? That way they can always validate the existing files in the project and reflect on this.

Apologies on the delay on getting back to you on this, life has been getting in the way.

Do you maybe know how we can achieve this with Material for MkDocs? I'm asking this because I had the same thought but didn't find a proper way of visually implementing this.

This could just be a couple of buttons, or even simpler just a bulleted list.

This was my initial thought also, but won't it be easier for users to have a fully implemented example? That way they can always validate the existing files in the project and reflect on this.

It might be easier, but as the tutorial is aimed at folks with no prior knowledge, we could guide them through setting up the development environment, starting watch mode, build and run a command and then write the tests. This would show the contributor the full end to end process and at the end they have built something from scratch. This would be a great way to learn. It's also a good way to show the developer experience.

Alright, it has been a while since I last updated this PR. Here are the changes I have made:

• Added a "Next Steps" section at the end of several articles to guide users toward follow-up articles.
• Included a few pathways on the landing page that users can follow to achieve specific goals.
• Updated some content to improve readability and ease of following.

I want to mention that I haven't incorporated the suggestions for the new command example. Personally, I believe it is much easier for users to understand and follow a real-world scenario rather than a hypothetical one. This way, users can also refer to the fully implemented files to compare their own scenarios.

Do you need help on this one @garrytrinder? It would be nice if we can merge it before the migration to docusaurus.

@Jwaegebaert, @garrytrinder: just to get the lay of the land: how far along is this PR? Do you think it's just crossing some t's and dotting some I's? Or might more zealous reading be in order?

Some zealous reading is always welcome 😄

I've done a second round of adjustments so it could always do with some tweaks here and there. But with Docusaurus around the corner like you said. We'll need to make some adjustments to this guide to include the Docusaurus architecture

In that case maybe we should leave it until after the docusaurus release...

Closing this to test Parker

@Jwaegebaert, @garrytrinder: just to get the lay of the land: how far along is this PR? Do you think it's just crossing some t's and dotting some I's? Or might more zealous reading be in order?

This had fallen off my list, however now that Docusaurus release has happened it seems like a good time to revisit this.

It's been updated to include all the changes regarding Docusaurus

Awesome initial review @garrytrinder, I've already applied most of these.

Nice review @milanholemans, very thorough! Most suggestions are applied. One thing I was curious about, I noticed there weren't any suggestions regarding the file contributing-guide.mdx. Maybe you forgot that one?

Nice review @milanholemans, very thorough! Most suggestions are applied. One thing I was curious about, I noticed there weren't any suggestions regarding the file contributing-guide.mdx. Maybe you forgot that one?

I left 1 comment there 😃. From what I can remember, that page was good 👍

@pnp/cli-for-microsoft-365-maintainers can we give this PR a shot and merge it in? 😄

@Jwaegebaert LGTM 🚀

Merged manually, nice work @Jwaegebaert!