pnp
Reflect the GitHub wiki and our docs
Originates from: https://github.com/pnp/cli-microsoft365/pull/4456#discussion_r1263855988
The idea is to review our current GitHub wiki docs and possibly move all of them to our docs. When we do this we should make sure all the links that reference the GitHub wiki also update to the new location.
ToDo
- [ ] Home Let's rewrite this with some handy links to the docs that talks about certain topics.
- [ ] All you have to know about Docusaurus We can safely remove this page.
- [x] #5206 GitHub Codespaces & Visual Studio Remote Development Container We include this in the docs.
- [x] #5533 PR checklist We include this in the docs.
- [ ] #5534 Spec checklist We include this in the docs.
Done
- [x] Adding a command -> Available on the docs site: Adding a new command
- [x] Adding new script sample -> Available on the docs site: Creating a new script sample
- [x] Submitting a PR -> Available on the docs site: Submitting your local changes
- [x] What to expect during a Pull request review -> Available on the docs site: What to expect during a Pull Request review
- [x] Minimal Path to Awesome -> Available on the docs site: Setup your development environment
Putting this on hold until #4456 is merged as this covers a few of these pages
What's the reasoning behind this change? The reason for keeping contributors docs in a wiki was the thinking that we've got two distinct audiences: contributors and users. User have generally no need to be on GitHub so all information for them is published in the docs. On the other hand, contributors spend more time on GitHub so we want to make docs readily available to them without sending them to another location and having them switch back and forth between the repo and the docs.
TBH I feel like how we have it now is ok. Similar to what @waldekmastykarz said, in web we have things like: how to use? Why to use? What are the commands? What are the features? Etc. All things a CLI use needs in a nice and guided form. Extending CLI is quite unique that IMO only few folks do. In this case the part to understand how to contribute properly, how we are gonna review the PR etc. May be found here, on our repo. Maybe before we change that we could open a question to our community in discord 🤔? @pnp/cli-for-microsoft-365-maintainers any other feedback?
What's the reasoning behind this change?
Pardon me for the confusion, I didn't provide the full context regarding this issue. This issue originates from PR #4456 where we will add a completely new section to our docs that's all about contributing to the cli. That will make it so the wiki becomes a bit redundant because information for our contributors will also be found on our site. At the moment the PR isn't merged yet so I was waiting on that until opening up the discussion here 😄
Honestly, I find the user experience regarding reading and navigating through an article way better than on GH wiki. I remember when I first started contributing that I found it rather difficult to gather all the resources that talk about how you can contribute. That's what we are aiming to enhance with the expanded getting started guide (with contributing) in the docs.
Thanks for clarifying @Jwaegebaert. When you say you struggled to find the necessary information to contribute: was it lack of specific content or the fact that even as a contributor you needed some information that was only in docs?
What do you think about the possibly disjointed experience where the code is in GitHub but the docs about contributing in the docs which are best accessible through a separate website?
Partially because of lack of content but I was already aware of this because I noticed this issue #2834. When I was doing some testing locally I always had the docs and GitHub open to do some research.
What do you think about the possibly disjointed experience where the code is in GitHub but the docs about contributing in the docs which are best accessible through a separate website?
How would you envision this? Currently, the guide I wrote up already includes partial segments of code to make everything a bit clearer. E.g.
https://github.com/pnp/cli-microsoft365/blob/2df7eaca1db225699645aad08ad357288946e1dc/docs/docs/contribute/new-command/build-command-logic.mdx#L51-L63
My original thinking was that by having the docs for contributors in the Wiki they're closer to the code and a part of the same repo UX. In other words, you don't need to go to another place to look at the info you need to contribute. Thinking of it some more though, when contributing you're not in GitHub, you're in the IDE, so perhaps we should consider how we could bring the docs there.
Having the guidance in the docs folder brings it closer to the code in the IDE, but I think we're missing discoverability and navigation. I wonder if it's something that we could solve with .md or if we'd need an extension that can reason about the part of command you're working on and can over you contextually relevant guidance inside the IDE.
Another thing that we need to consider is how mdx is rendered inside the IDE so that you're not missing anything important.
Personally, I think it doesn't really matter where our contribution docs are hosted. At least, it doesn't matter to me. But I have to say, there are some benefits if we move it to our docs website.
The most obvious one is of course that our docs a visually more appealing and nicer to read.
Apart from that, in the past, we had a few people creating issues in our backlog because there were outdated stuff/typos/broken links/... in our contribution docs. Then I always had to disappoint them because they couldn't fix it themselves, only maintainers can edit these wiki pages. If we move it to our docs, everyone would be able to fix/enhance these pages which benefits everyone.
Another benefit would be that our AI assistant would be able to answer questions about contributing.
As I mentioned before, I can live with both scenarios. If we host it in GitHub, I'm fine, if we host it on our docs, also good for me. To be honest I don't understand why these guides shouldn't be hosted on our docs website. As long as they are accessible and centrally located in 1 place, it's good, right?
As far as I know, most of the PnP solutions are hosting their contribution guidelines on their docs. So actually it seems like we are currently the odd one out 😊
- PnPjs
- PnP Core
- PnP PowerShell
- PnP SPFx Controls
- PnP Modern Search
- Probably many more...
Our current decision is a couple years old now so we can definitely revisit it as things have changed. I suggest that we look specifically at the developer experience of our contributors and how can we make it as convenient as possible for them to lookup docs as they're working on the different issues.
Before we commit to a solution, let's look at different options that we could consider.
As mentioned before, I'm kinda neutral here. Both approaches are fine. But when I put the pros and cons next to each other, in my opinion, there's a clear winner being moving it to our docs. Since Jasey also made a huge PR already that has been reviewed a couple of times, it would be sad for him to have to drop this PR.
I suggest that we look specifically at the developer experience of our contributors and how can we make it as convenient as possible for them to lookup docs as they're working on the different issues.
These guidelines are just to get people started. New contributors will read them once, maybe twice but it's not something that that needs to be consulted often. Discoverability is indeed important, but to be honest they are easier to discover in our docs than on GH. When I started contributing to PnP projects I just checked their docs website for a getting started guide. I wasn't even aware that something like GH Wiki pages existed.
In Jasey's PR, we're explaining how to set up your fork and clone it locally. I think if you don't know how to set up a fork, you probably don't know there's something like GH Wiki pages either.
One thing we could do is host it on our docs and create 1 GH Wiki page that points them to the right page on our docs.
I'm a little confused about why this discussion is arising now. Honestly, I'm okay with both approaches, but a lot of work has already gone into creating the PR that adds this to the docs and it would be a bummer to delay this yet again.
Having the guidance in the docs folder brings it closer to the code in the IDE, but I think we're missing discoverability and navigation. I wonder if it's something that we could solve with .md or if we'd need an extension that can reason about the part of command you're working on and can over you contextually relevant guidance inside the IDE.
The docs that have been written are quite extensive and reference a real command, so users can always have a peek in their IDE at how spo group get is implemented.
....Thinking of it some more though, when contributing you're not in GitHub, you're in the IDE, so perhaps we should consider how we could bring the docs there.
VS Code extension 😁. Just saying 😋 plus the current PnP CLI for M365 VS Code extension already exposes our docs (docs coming from the website not wiki) directly in VS Code. Currently, we only show command docs but it will be an easy feature to implement to add some other pages like regarding contributing. aaaand we also may integrate our AI search directly in this extension (it is already on my neverending ToDo list 😁). So to sum up, another argument to those that @milanholemans pointed out (BTW awesome suggestions) to have more docs in website rather than in GH wiki is that it will be easier to add it to CLI for M365 VS Code extension
I'm a little confused about why this discussion is arising now. Honestly, I'm okay with both approaches, but a lot of work has already gone into creating the PR that adds this to the docs and it would be a bummer to delay this yet again.
Sorry for that. TBH I have a feeling I created this confusion in the first place 🙏. But TBH there is sooo many going on that it's hard to catch up plus this transfer from GH wiki to the website with contributor docs I think is something most of us (maintainers) should have a check and chance to express an opinion, even if it takes a bit more time, let's revisit this and pick the best option
Update after an internal call. We'll move our wiki information to the docs as the GitHub wiki feature isn't handy with several pages. As soon as #4456 is merged we'll review what additional changes need to be made.
#4456 has been merged, do we need some additional info or should we open this one up?
'On hold' can definitely be removed here.
For each page, I updated the specs with the pages that currently exist on the docs site. For the others I've the following suggestions:
- [ ] Home
Suggestion: Let's rewrite this with some handy links to the docs that talks about certain topics.
Could this be removed?
Suggestion: We include this in the docs as well.
- [ ] PR checklist
Suggestion: We include this in the docs as well.
- [ ] Spec checklist
Suggestion: We include this in the docs as well.
Could this be removed?
I think we can safely remove this wiki page yes.
@pnp/cli-for-microsoft-365-maintainers, any further thoughts regarding this topic?
@Jwaegebaert do you think we may (at least some parts) open up for others to contribute for hacktoberfest?
That's a good idea. Should we split these tasks up into different issues and spec them out more clearly? They could be some good good first issue issues 😄