Accepting PRs for the wiki?

[NWoodsman]

Is the Dotnet Foundation and/or the WPF team willing accept PRs to improve the Wiki? I would like to make contributions to fully document the wpf build process. By doing so, it will enable discussion and debugging of build steps when users fail to successfully build, and they can then provide citation to sections of the wiki.

I can envision such topics as:

• Local machine preparation
  • Install visual studio
  • Import vsconfig
• Configure global.json
• Run build.cmd
  • Explain the possible command line arguments for this
  • High level documentation of the build scripts called by build.cmd
    • Description of the build tools and dependencies that get installed and/or are required as part of the build process
• Documentation of the CI workflow and explanation
• How to substitute build artifacts into a WPF project to step into WPF code using generated PDBs

I'm not sure this information is coherently documented anywhere else currently on the entire web so it makes sense to do so here. This information appears to exist in incomplete fragments of github issues, discussions, inside the project .md files, and other various places.

[miloush]

Have you seen https://github.com/dotnet/wpf/tree/main/Documentation?

[NWoodsman]

@miloush I have seen the documentation at https://github.com/dotnet/wpf/tree/main/Documentation and read many of the markdown files. Please be aware that I am a hobbyist developer, and therefore I can only describe the current documentation from an "outsider" perspective. My thoughts below might sound downright silly to a full time or senior developer who have a conceptual grasp of this project /repo.

If I were project lead describing what is contained in https://github.com/dotnet/wpf/tree/main/Documentation, I would characterize the information as not able to pass the "who, what, when, where, why" test.

• Who should understand the content?
• What is the purpose of the content?
• When is the information contained relevant?
• Where does the information map into the repository?
• Why document this particular information?

Let's look at an example:

packaging.md

As stated above, I don't believe this file has enough documentation to answer the above questions.

I will give some additional specific critique of the above file:

• What is 'packaging'?
• What are the "WPF Arcade SDK tools?"
• What is the purpose of the Microsoft.DotNet.Arcade namespace?

I personally have done some research to provide answers to these questions. (My guess is that actual MSFT developers recieve this information in their first week assigned to the WPF project.)

Below, I placed my understanding of these answers in a conceptual wiki organization to explain packaging.md:

WPF

0. Definitions and Overhead

   • 0.1 - Definitions

     • Definitions is defined as "a narrative explanation of every abstraction / abstract terminology introduced in the WPF repo."

       • for example, "Presentation" is used in "Windows Presentation Foundation", PresentationBuildTasks.dll, etc. Presentation would be defined here.

     • (No definitions implemented yet)

   • 0.2 - Overhead

     • Overhead is defined as "everything you need to know that this documentation will refer to that is otherwise not documented within this documentation."

     • 0.2.1 - Dot Net

       • 0.2.1.1 - Dot Net Core

         • 0.2.1.1.1 - Dot Net Arcade

           • Tools that provide common build infrastructure for multiple .NET Foundation projects.

           • Arcade is intended to provide well-understood and consistent mechanisms for consuming, updating, and sharing infrastructure across the .NET Core team.

           • Github Repo

1. Critical path

   • The definition of "critical path" is the steps for a single developer to turn source code in to a consumable dll or nuget package.

   • 1.1 - Environment Setup

     • (No documentation yet)

   • 1.2 - Building

     • 1.2.1 - Obtaining the correct toolset that WPF requires

       • 1.2.1.x - WPF Arcade tools

   • 1.3 - Build output

     • 1.3.1 - WPF API

       • this section describes the build output for public consumers who intend to consume the WPF API by creating a project built atop WPF.

       • 1.3.1.1 - Library .dll output

       • 1.3.1.2 - Nuget package output

   • 1.4 - Incorporating build artifacts into a consumer project

     • (Not implemented)

2. The WPF Ecosystem

   • 2.1 - Documentation

     • How this repo generates documentation

   • 2.2 - Other build outputs

     • 2.2.1 - DotNet Arcade SDK Output

       • This Sdk contains all the build props, targets and scripts needed to build WPF.

   • 2.3 The Team Ecosystem

     • 2.3.1 - The WPF Microsoft Team

     • 2.3.2 - The open source community

---

As you can see in the loose wiki organization above, the "overhead" to understand packaging.md spans multiple locations in chronology:

• As it applies to 0. Definitions and Overhead, to understand packaging.md, you must understand that an entirely different repo called Arcade exists external to the WPF repo/project.
• As it applies to 1. Critical Path, to understand packaging.md, you must understand that the Arcade namespaces don't contribute to the WPF consumer API; no shippable code is omitted.
  • Because no shippable code is omitted by Arcade required for the WPF API, packaging.md documentation isn't necessary in the critical path; except for establishing build and tooling dependencies required to build the API.
• As it applies to 2. The WPF Ecosystem, most of the content of packaging.md belongs here as a subsection to explain how the WPF repo interops with the Arcade toolsets.

---

Hopefully you see that the above proposed wiki chapters:

1. Provide an easy to understand, 3 step chronology to understanding the project (1. Definitions & Overhead, 2. Critical path, 3. Ecosystem)
2. Give critical contextual information that is missing from the current documentation
3. Serves as a basic first PR to establish the wiki sections.

[miloush]

I just wanted to make sure you are aware of that, as some of the topics you mentioned in your original question are touched upon in there. I don't think anyone would object you making contributions to wiki and even in the worst case it would still be valuable to have it written up for others.

[NWoodsman]

I'm a bit "opinionated" on how the documentation should be presented. The three steps presented are an opinion: they are both chronological and ordered by dependency ; You can't expect to build the project without the basic knowledge learned in the basic definitions. And you shouldn't care about Arcade until you can build the project minimally. I borrow the term "critical path" from a different domain, construction project management.

[miloush]

If a particular style works for you then I am sure there are other people who would feel the same. An opinionated presentation is better than no documentation.