Runtime: Move important information from Wiki to Docs

[wtgodbe]

We should go through https://github.com/dotnet/corefx/wiki & move anything important to https://github.com/dotnet/corefx/tree/master/Documentation, then abandon the wiki.

CC @karelz @danmosemsft

[davidsh]

We should go through https://github.com/dotnet/corefx/wiki & move anything important to https://github.com/dotnet/corefx/tree/master/Documentation, then abandon the wiki.

I think some of the information needs to be placed on docs.microsoft.com in the appropriate place. For example, some behavior differences between .NET Framework and .NET Core for networking APIs should be documented in the Remarks section of the appropriate API.

E.g.: HttpResponseMessage.EnsureSuccessStatusCode

[ViktorHofer]

This needs to happen before we merge repositories. cc @carlossanlop @Anipik in case you are interested helping here.

[ViktorHofer]

@carlossanlop would you want to help out here? We need to do this before the repo consolidation happens.

[carlossanlop]

Sure I can help with this. Viktor says we need in the next month, before November ideally.
cc @karelz

[karelz]

Yesss! I hope we can retire the XXXL long docs in Docs directory in favor of the new-contributor- friendly style docs we have on wiki 🤗
De-duplication would be first great step.

[ViktorHofer]

Great, Carlos I'll send you some ideas.

[carlossanlop]

@ViktorHofer @karelz here is my plan, 5 stages:

• [ ] Backup all the *.md files located in the wiki repo dotnet/corefx.wiki inside a temporary folder in the dotnet/corefx repo, so we don't block the repo merge work, and we don't worry about deleting that info permanently. I will do this immediately.

• [x] Keep the relevant *.md files, delete the useless/obsolete ones. I went through all the files and this is my initial proposal:

|Keep|*.md filename|Why|
|-|-|-|
|No|_Sidebar.md|Nothing useful|
|No|ApiCompat.md|Historical info|
|No|Build-and-run-tests.md|Already documented here and here|
|Yes|Building-.NET-Core--2.x-on-FreeBSD.md|In case we need to preserve the 2.X instructions|
|Yes|Building-.NET-Core-3.x-on-FreeBSD.md|Allegedly already documented here, but not explicitly.|
|No|Checking-out-the-code-repository.md|We should not maintain a git tutorial|
|No|Contributing.md|Nothing useful|
|No|Contributions.md|Nothing relevant today|
|No|Creating-a-Pull-Request.md|We should not maintain a git tutorial. PR rules are documented here.|
|No|Development-environment-setup-for-Linux.md|Already in docs, and up to date|
|No|Development-environment-setup-for-MacOS.md|Already in docs, and up to date|
|No|Development-environment-setup-for-Windows.md|Already in docs, and up to date|
|No|Enabling-New-OS.md|Useful instruction links, but they already live somewhere else. Some links are merged fixes.|
|No|git-reference.md|We should not maintain a git tutorial|
|No|Hackathon.md|Obsolete event|
|No|Home.md|Nothing relevant|
|No|HTTP-2-Implementaiton-Status.md|Networking team is actively using it. I asked them to move it to GitHub projects/issues.|
|No|Issues.md|Nothing useful|
|No|Joining-.NET-Core-team.md|Must move to internal document.|
|Yes|Links.md|Keep the conference links, remove irrelevant links|
|No|New-contributor-docs---TODO-list.md|Nothing useful|
|No|New-contributor-docs.md|Links are obsolete.|
|Yes|Pick-Issue.md|Summarize the label descriptions|
|No|Setting-up-the-development-environment.md|Nothing useful|
|No|UWP-Compat.md|Obsolete|

• [ ] Move the information in the wiki *.md files into their relevant section in the corefx Documentation folder.

• [ ] Restructure the documentation. @ViktorHofer offered a suggested initial structure, we can discuss/expand it further:

  • docs
    
    
    
    • design
    
    
    • project
    
    
    • manpages
    
    
    • botr
    
    
    • coding-guidelines
    
    
    • workflow
      
      
      
      
      
      • building
      
      
      
      • testing
      
      
      
      • profiling
      
      
      
      • performance
      
      
      
    
    

• [ ] Split large documentation files into smaller ones, as suggested by @karelz above.

• [ ] Remove duplication. I found many topics that are explained in multiple places, we should substitute them all with a link to a central, unique *.md page. For example, searching for RebuildAndTest instructions in the corefx repo returns many pages where running unit tests is explained.

Updates:

• Updated the table by removing the documents discussed below (networking, join, apicompat).

[carlossanlop]

Update: I was told the corefx repo and the wiki won't get destroyed, so I'll skip step 1 from my previous comment.
I will focus on only bringing the relevant information into our repo.

[jkotas]

ApiCompat.md Historical info

This information is maintained in documentation and https://github.com/Microsoft/dotnet-apiport database. We do not need a stale copy in the repo.

HTTP-2-Implementaiton-Status.md Networking team is actively using it

github issues and projects are the appropriate tools for tracking project status. This should not be committed as file. Convert to issue or project.

Joining-.NET-Core-team.md Save this

Information specific to Microsoft employees should not live on github. It should live in an internal OneNote.

[danmosemsft]

Information specific to Microsoft employees should not live on github. It should live in an internal OneNote.

I noticed it's already here:

https://github.com/dotnet/core/blob/master/Documentation/microsoft-team.md#configure-your-github-account-as-a-microsoft-employee-recommended

[ViktorHofer]

@carlossanlop can you please come up with a plan for the categorization? Would like to know which documents would go into which directory. Having a common set of categories with coreclr and core-setup will help us consolidate the docs at a later point.

[ViktorHofer]

As stated in the PR, we still want to disable the WIKI feature in Corefx. That's listed as pre-requisite for the consolidation as it's a good metric when docs are ready.

[jkotas]

we still want to disable the WIKI feature in Corefx

That is nice to have. The Wiki was limping along in CoreFX for number of years. It is not a big deal if it continues limping along in the archived CoreFX forever.

[carlossanlop]

@jkotas thanks for sharing your findings. Based on what you shared:

• I will not add the ApiCompat document since it's stale.
• I will ask the Networking team to delete this document and convert it to individual issues. We won't backup that file, so they should do it soon.
• Regarding the OneNote with Microsoft onboarding information, I have conflicting information because @danmosemsft shared a link to a page containing instructions for MS employee onboarding. It seems we don't have a problem sharing this kind of information publicly (and only MS employees can follow these instructions anyway). Based on this, I will not backup that wiki file containing information, but instead, I will add a hyperlink in our documentation pointing to the page shared by Dan. That way we avoid duplication of information. Does this sound good or would you prefer something else?

@jkotas @ViktorHofer I noticed the majority of the documents we have in the corefx wiki contained documentation planning information, not the documentation itself. The original idea was to delete the wiki. At the very least, we should disable the one in corefx, and avoid creating one in the new repo. Otherwise, we will start duplicating documentation again. What do you think?

[danmosemsft]

That is nice to have. The Wiki was limping along in CoreFX for number of years. It is not a big deal if it continues limping along in the archived CoreFX forever.

I'd rather delete it - since it causes confusion through having out of date info. I haven't gone through what's in there and it's good @carlossanlop is looking through it but I'm guessing it would not be a big loss to simply delete it.

[jkotas]

only MS employees can follow these instructions anyway

These piecemeal instructions are incomplete. The full instructions to get a new hire in CoreCLR/CoreFX running are on internal one note that we would not be comfortable sharing.

Internal instructions do not belong to open source repositories. It does not look good for external contributors, and these instructions are a risk in that somebody will try to update them with details that are not supposed to be public.

[jkotas]

I noticed the majority of the documents we have in the corefx wiki contained documentation planning information, not the documentation itselt

These are all @karelz ideas that he did not have time to finish.

[jkotas]

avoid creating one in the new repo.

Yes, we should not even think about recreating the wiki in the new runtime repo.

[carlossanlop]

@ViktorHofer @danmosemsft @jkotas I modified the Documentation README.md to merge corefx and coreclr documentation, and include the wiki data I considered useful from my table above.
Can you please review it?

This is how it would look:
https://github.com/carlossanlop/corefx/tree/NewReadme/Documentation

I should not submit a PR yet because I first need to organize the files.

[jkotas]

merge corefx and coreclr documentation

I do not think this issue is about merging corefx and coreclr documentation. Merging corefx and coreclr documentation will be a very large undertaking and I think it is better to be done only after everything is in the runtime repository.

This issue is about what is at the top - nothing more, nothing less:

go through https://github.com/dotnet/corefx/wiki & move anything important to https://github.com/dotnet/corefx/tree/master/Documentation, then abandon the wiki.

[carlossanlop]

@jkotas The documentation merge task will eventually have to be done, so I'll keep the branch in my fork with the proposal for future reference.

Regarding porting wiki info, I will submit a PR soon. The change will be small.

[ViktorHofer]

@carlossanlop can we disable the wiki now?

[carlossanlop]

@ViktorHofer Yes we can.

[ViktorHofer]

Thanks, I just disabled the wiki. I also cloned it locally - in case somebody wants to restore something, ping me.

[ViktorHofer]

Here's the link to a backup: https://microsofteur-my.sharepoint.com/:u:/g/personal/vihofer_microsoft_com/EfekSugu7JJHrC5_QwEbL_QBvgBs21tAb4GUsVhRH6Zf-A?e=2jzaCd