Powertoys: Move end-user facing docs to docs.microsoft.com

[Aaron-Junker]

crutkas update:
We will move end-user documentation into docs.msft from the wiki.

Work items include creating a new topology for documentation since docs can do a better nav system than the wiki

---

original statement:

At the moment there are two places where docs are:

• In the wiki
• In the doc folder

And why is this so?

Because the files in the doc folder should be editable by all people and not everyone can edit the wiki.

So I had a idea:

1. Clone the wiki to a new repository.
2. Modify the msftbot or a other bot, so that he:
3. Change files in the repository, when something is changed in the wiki
4. Change the file in the wiki, when something is changed in the repository main branch (!= readme.md)
5. So it's a mirror who everyone can make PR on the wiki and all docs can be accessed through the wiki.

Checklist:

• [ ] Create mirror repository
• [ ] Create bot
• [ ] Move docs
• [ ] Create overview pages for the doc files
• [ ] Change links

Please tell me your suggestions or your opinion on this

[ghost]

@Aaron-Junker I would like to help but is it possible clone a wiki?

[Aaron-Junker]

@alannt777 Yes it is

But before you make something i want to know what the PT core team thinks about that.

[ghost]

Ok

[ghost]

cc @crutkas

[ghost]

@Aaron-Junker Please tell me how can I help?

[ghost]

A git pull from the mirror repo and a git push to the wiki and vice versa will sync those up. We need a bot to automate this process to sync in real time

[Aaron-Junker]

Yes. Can you write a bot or a action which make this?

[ghost]

@Aaron-Junker

Yes I think I can write a python script that can be triggered by GitHub actions on merge. I will experiment in alannt777/PowerToys-Docs

[ghost]

I am not an expert in using GitHub actions. So please help me. I will invite you and @crutkas as collaborators

[Aaron-Junker]

@alannt777 Wow amazing. But keep in mind that it isn't discussed yet with other PT team members

[ghost]

@alannt777 Wow amazing. But keep in mind that it isn't discussed yet with other PT team members

I know. I am waiting

[ghost]

I love PowerToys. I would love to contribute somehow. I don't know C++ and I am a total beginner in C# and .NET. So this is my best bet

[Aaron-Junker]

@alannt777 Every help is welcome.

Tip:mirror the docs to the wiki in your repository. Because on this wiki you don't have write access

[ghost]

Tip:mirror the docs to the wiki in your repository. Because on this wiki you don't have write access

But I am experimenting directly in that repository

[ghost]

Plan (if this gets approved):

• Store credentials (in GitHub Secrets) of a dummy user account with access to wiki and that repo
• Somehow use that credentials to git push using GitHub Actions

[ghost]

Experiment in this repository. Will transfer ownership if required.

[crutkas]

Can we create an Teams sync on this? I feel we could quickly talk about this and the 'why'. @dedavis6797 is going through and helping make sure we are being much more clear for both dev and end user onboarding. Everything is fair game to improve.

Here is the current thinking:

• Dev docs -> in repo
• End user docs -> Wiki
• Specs -> Wiki
• Triage queries -> Wiki

Why:

Wiki allows us to be sure we can continue on master. We broke links for the app as we continued core work and that is why we shifted into the wiki for these docs. It also allows the main repo to stay slimmer.

Well, what about the readme, that is in the repo ... While true, we can be a bit regimented about updating that and don't keep

• Wiki for specs, images are big and causes long term weight to the repo
• wiki for triage stuff, easy to tweak that stuff without the heavy CI system.

For dev docs, since these need to typically be in sync with the current main branch, we want these here. They don't sync with a release and are highly contextual.

Why is the Wiki not open

The option for Wiki is totally open or not open. We don't want anyone to go in and change without review.

[ghost]

@crutkas the mirror repository and wiki will sync up. The mirror repository exists so that we can file issues on the wiki (we can actually do that on this repository) and have pull requests to change the wiki (which is not possible in this repository)

Why allow changes through PRs?

Take terminal docs for example. It is an open repository. This allows the community to suggest changes and give Pull Requests to make the docs better

[ghost]

It also allows the main repo to stay slimmer.

That's why these are two separate repositories.

For dev docs, since these need to typically be in sync with the current main branch, we want these here.

That's fine because dev docs are very important and will update quickly as we update the code. It makes sense to keep it in this repository

[crutkas]

So I feel like we're jumping to solutions before we actually talk about what the problems are. There are three different set of users here and we have three different sets of docs.

• People interested in helping build PowerToys
• People interested in using PowerToys
• People interested in helping maintain the PowerToy repo (aka me 😜)

The Terminal docs in Docs.msft are targeting end user. These currently live in our wiki.

Is the ask here to make it easier to contribute to end user docs? @mattwojo what is the process to get PowerToys into the Docs repo for end user?

[ghost]

Is the ask here to make it easier to contribute to end user docs?

I think that's what @Aaron-Junker meant while opening this issue.

[ghost]

PowerToys is a rapidly growing project and will have more awesome 'toys' and more features that could make maintaining the wiki difficult. That is why I think this issue is a valid concern

[Aaron-Junker]

@crutkas @alannt777 I think you both got the point. I wnt to make it easier to contribute to the end user docs.

[ghost]

vscode's wiki works in the same way. Look at their wiki repo

[ghost]

Any updates? @Aaron-Junker @crutkas

[mattwojo]

I'm not sure that I've totally tracked with this conversation, but I'll weigh in that I believe it's best to align with what Windows Terminal (and WSL and others) are doing in regard to docs... they started with docs in their product repo (Terminal's product repo), then moved to https://docs.microsoft.com/windows/terminal (Terminal's docs repo), as they moved from preview to GA. Terminal is a bit unique as it does contain a mix of developer-focused content (standard for docs.ms) and end-user-focused content (usually on microsoft.com or support.ms), which makes sense given that most terminal end-users ARE developers... but I think that PowerToys could still work in the same way.
The docs.microsoft.com is set up to support user community contributions.. so the PT team would just need to help with monitoring, but if we set it up along side Windows Package Manager in the windows-uwp repo, then we have someone assigned to help with triaging any issues or PRs that come in.
The PowerToys repo would still need to have a readme doc about how to contribute to the product (as oppossed to the docs) and the wiki could still have the roadmap, kanban, and preview announcements...
How does that sound?

[mattwojo]

If moving PowerToys docs to docs.ms sounds like a good plan, just follow up with me @crutkas and I can help get everything set up to migrate over. Questions? Should we do a sync call first?

[crutkas]

We need to first create the outline / topology for what pages are there. I feel that FZ and PT Run could be broken into smaller pages. We also need a page there for contributing back / developing that points back to the GH dev docs.

@dedavis6797 this is something for the e2e experience we should be thinking about / you should weigh in on.

[ghost]

If the end-user docs will be hosted in docs.microsoft.com, the plan that I proposed above will not be relevant anymore. So I am abandoning my plan

[crutkas]

@alannt777 that is the plan, lets create the topology here and we can adjust the docs here and move them over. This will help @mattwojo for the initial creation of stuff and we can quickly do the swap.

We'll have to update AKA links as well (that is a me job).

[Aaron-Junker]

Cool thing.

[ghost]

Any updates?

[Aaron-Junker]

Any updates?

Work in progress.

[ghost]

How do you know? Was I missing something?

[Aaron-Junker]

How do you know? Was I missing something?

I've mailed with @crutkas . And I don't know if I'm allowed to publish such information.

[crutkas]

Tentative for .27. Should have it ready for review by then.

[ghost]

@crutkas is it possible to see the repo before going live in docs.microsoft.com?