The WSL networking page needs major rework!

[chjfth]

You said "YouYouYou...", and reader has to "GuessGuessGuess". That was frustrating, so I reworked it.

[learn-build-service-prod]

Learn Build status updates of commit 418c9fe:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
WSL/basic-commands.md	⚠️Warning	View	Details
WSL/networking.md	⚠️Warning	View	Details
WSL/media/network-mirrored-mode1.png	✅Succeeded	View
WSL/media/network-mirrored-mode2.png	✅Succeeded	View
WSL/media/network-nat-mode.png	✅Succeeded	View

WSL/basic-commands.md

• Line 174, Column 38: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#identify-ip-address' in 'networking.md'.

WSL/networking.md

• Line 143, Column 1: [Warning: invalid-note-section] Text in the first line of Note/Section/Video is not valid. Will be rendered to <blockquote>
• Line 156, Column 1: [Warning: invalid-note-section] Text in the first line of Note/Section/Video is not valid. Will be rendered to <blockquote>

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[learn-build-service-prod]

Learn Build status updates of commit ca0d71d:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
WSL/basic-commands.md	⚠️Warning	View	Details
WSL/media/network-mirrored-mode1.png	✅Succeeded	View
WSL/media/network-mirrored-mode2.png	✅Succeeded	View
WSL/media/network-nat-mode.png	✅Succeeded	View
WSL/networking.md	✅Succeeded	View

WSL/basic-commands.md

• Line 174, Column 38: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#identify-ip-address' in 'networking.md'.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[AlexDev404]

Although it is ok, I think there is a misconception between making a contribution versus an attempt to take things into your own hands.

[learn-build-service-prod]

Learn Build status updates of commit ee5d485:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
WSL/basic-commands.md	⚠️Warning	View	Details
WSL/networking.md	⚠️Warning	View	Details
WSL/media/network-mirrored-mode1.png	✅Succeeded	View
WSL/media/network-mirrored-mode2.png	✅Succeeded	View
WSL/media/network-nat-mode.png	✅Succeeded	View

WSL/basic-commands.md

• Line 174, Column 38: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#identify-ip-address' in 'networking.md'.

WSL/networking.md

• Line 158, Column 1: [Warning: multiple-h1s - See documentation] Multiple H1s(H1 'For example, L3 has a TCP server program listening on or even on , then, WinHost can connect to to reach the server. This "proxy listening port" feature makes it as if the WSL server program is listening on WinHost itself.') are not allowed. You can only have one top-level heading.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[mattwojo]

Hey @chjfth - Thank you for this PR and all of the rewriting that you put into it!

There are some good updates here! The issue is that it's too much in a single PR and trying to accomplish too many things for us to accept and merge it all in one PR.

Would you be able to break this up a bit into more targeted PRs... for example, the image updates in a single PR, and content rewrites in a different PR, with one PR per section?

I'm sorry to ask you to do this, but we are having too much trouble merging as-is. A good amount is also voice and tone or wording and formatting preferences that are subjective. We do have a writing style guide that offers some specifics that I imagine this doc could benefit from: https://learn.microsoft.com/contribute/content/style-quick-start But again, we would need more specific PRs with specific descriptions such as "Improve focus on intent" or "Apply more concise language" or "Use more accessibile terms", etc.

There are some helpful tips about creating smaller PRs here: https://gist.github.com/sktse/569cb192ce1518f83db58567591e3205

Please let me know what you think and if this seems doable.
Thanks again!

[chjfth]

Glad to see your response after nearly 9 months, @mattwojo. Yes, this should be doable, and I'm wishing to push it forward.

Let me first respond to the two web links you provide.

• Microsoft Learn style and voice quick start : This guideline is great. Use short, concise sentences, use words and syntax structures the readers feel easy to digest. I'm always sticking to these principles. On the other hand, the mass Win32 API MSDN reference documents(20+ years) and Windows Internals 6th-ed book(10+ years) are awash with bad examples.
• How to Keep Pull Requests Manageable : I generally agree that small change sets makes git merging easier, and you can do it piece-by-piece.

9 months ago, I had hoped that you could merge in first 80% from my new networking.md (because those are totally rewritten by me) and leave the final 20% intact. I think this is mostly true even today, because there are only a few minor commits from other people on networking.md.

I'm not very clear why is it hard/infeasible to "accept and merge it in ONE PR". Maybe there are some details I'm not aware of. If you feel ease, give me some detail. If it could be cumbersome, then save it.

Now the topic.

[Q1] I need to confirm a key question before going on. Do you think my updated networking.md content is acceptable for you to start merging? For example, I invent the word WinHost to represent the the physical Windows machine, which is quite not-MSDN-style. But I insist using it, for the sole purpose that WinHost makes later wording very clear and concise(used 40+ times in later text).

If it is OK, then the operation details. I can do it from beginning.

[Q2] Is it OK that I do this:

1. Commit all new images in one shot. (get SHA1)
2. Commit my first H2 paragraph "The big picture". (get SHA2)
3. Commit my second H2 paragraph "How to determine current networking mode for a WSL instance?". (get SHA3)
4. Commit my second H2 paragraph "WSL Networking behavior". (get SHA4) // This title is not very cognitive, may need better phrasing.

Or shall I break them apart into smaller commits?

[Q3] Then when shall I delete the old first 80% content? Before I add my first H2 paragraph or after all my H2 paragraphs have been added? (assume I get SHA5)

[Q4] Shall I create a pull-request as soon as I commit an H2 paragraph, or, create one pull-request after all paragraphs are committed?

[AlexDev404]

Glad to see your response after nearly 9 months, @mattwojo. Yes, this should be doable, and I'm wishing to push it forward.

Let me first respond to the two web links you provide.

• Microsoft Learn style and voice quick start : This guideline is great. Use short, concise sentences, use words and syntax structures the readers feel easy to digest. I'm always sticking to these principles. On the other hand, the mass Win32 API MSDN reference documents(20+ years) and Windows Internals 6th-ed book(10+ years) are awash with bad examples.
• How to Keep Pull Requests Manageable : I generally agree that small change sets makes git merging easier, and you can do it piece-by-piece.

9 months ago, I had hoped that you could merge in first 80% from my new networking.md (because those are totally rewritten by me) and leave the final 20% intact. I think this is mostly true even today, because there are only a few minor commits from other people on networking.md.

I'm not very clear why is it hard/infeasible to "accept and merge it in ONE PR". Maybe there are some details I'm not aware of. If you feel ease, give me some detail. If it could be cumbersome, then save it.

Now the topic.

[Q1] I need to confirm a key question before going on. Do you think my updated networking.md content is acceptable for you to start merging? For example, I invent the word WinHost to represent the the physical Windows machine, which is quite not-MSDN-style. But I insist using it, for the sole purpose that WinHost makes later wording very clear and concise(used 40+ times in later text).

If it is OK, then the operation details. I can do it from beginning.

[Q2] Is it OK that I do this:

1. Commit all new images in one shot. (get SHA1)
2. Commit my first H2 paragraph "The big picture". (get SHA2)
3. Commit my second H2 paragraph "How to determine current networking mode for a WSL instance?". (get SHA3)
4. Commit my second H2 paragraph "WSL Networking behavior". (get SHA4) // This title is not very cognitive, may need better phrasing.

Or shall I break them apart into smaller commits?

[Q3] Then when shall I delete the old first 80% content? Before I add my first H2 paragraph or after all my H2 paragraphs have been added? (assume I get SHA5)

[Q4] Shall I create a pull-request as soon as I commit an H2 paragraph, or, create one pull-request after all paragraphs are committed?

Your message comes across as a bit dismissive, complacent and disrespectful especially considering you're addressing someone from Microsoft. A more thoughtful and positive tone might help keep the conversation constructive and be more likely to guarantee a reply.