Update existing documentation and add glossary file (#186)

mslukebo · web-flow · commit 94f415a55604 · 2022-02-01T14:19:54.000-08:00
* Slight edits to existing documents and add glossary

* Combine sentences

* Address more comments

* Address feedback

* Grammar

* Fix now-dead link

* Alphabetize
diff --git a/README.md b/README.md
@@ -29,15 +29,15 @@ For help with getting started and developing SDK plugins, refer to the [document
 
 ## Projects in the SDK Solution
 * `Microsoft.Performance.SDK`: Software library for building SDK plugins
-* `Microsoft.Performance.SDK.Runtime`: Runtime for loading and processing data from plugins
-* `Microsoft.Performance.SDK.Runtime.NetCoreApp`: .NET Core version of `Microsoft.Performance.SDK.Runtime`
+* `Microsoft.Performance.SDK.Runtime`: Runtime for loading and processing data from plugins. Plugins should not depend on this library
+* `Microsoft.Performance.SDK.Runtime.NetCoreApp`: .NETCore-specific functionality of `Microsoft.Performance.SDK.Runtime`
 * `Microsoft.Performance.SDK.Toolkit.Engine`: Interface for programmatically manipulating, cooking, and accessing data from SDK plugins
 * `Microsoft.Performance.SDK.Tests`: Tests for `Microsoft.Performance.SDK`
 * `Microsoft.Performance.SDK.Runtime.Tests`: Tests for `Microsoft.Performance.SDK.Runtime`
 * `Microsoft.Performance.SDK.Runtime.NetCoreApp.Tests`: Tests for `Microsoft.Performance.SDK.Runtime.NetCoreApp`
 * `Microsoft.Performance.SDK.Toolkit.Engine.Tests`: Tests for `Microsoft.Performance.SDK.Toolkit.Engine`
-* `Microsoft.Performance.SDK.Testing`: *description coming soon*
-* `Microsoft.Performance.SDK.Testing.SDK`: *description coming soon*
+* `Microsoft.Performance.SDK.Testing`: General utilities for authoring tests
+* `Microsoft.Performance.SDK.Testing.SDK`: SDK-specific utilities for authoring tests 
 * `PluginConfigurationEditor`: *description coming soon*
 
 ## Known SDK Driver Plugin Compatibility
@@ -46,6 +46,10 @@ This repository tracks which versions of the SDK are compatibile with certain SD
 
 This information is listed in the [known SDK driver compatibility lists](./documentation/Known-SDK-Driver-Compatibility/Overview.md) document.
 
+## Getting Started
+
+Refer to the [documentation folder](./documentation/Overview.md) for help with creating SDK plugins.
+
 ## Coming Soon
 
 Team is actively working to provide better documentation, more samples, and several in-depth tutorials.
diff --git a/documentation/Glossary.md b/documentation/Glossary.md
@@ -0,0 +1,195 @@
+# Glossary
+
+* [AboutInfo](#aboutinfo)
+* [Column](#column)
+* [ColumnConfiguration](#columnconfiguration)
+* [ColumnRole](#columnrole)
+* [CompositeDataCooker](#compositedatacooker)
+* [CustomDataProcessor](#customdataprocessor)
+* [DataCooker](#datacooker)
+* [DataSource](#datasource)
+* [DynamicTable](#dynamictable)
+* [Pivot Column](#pivot-column)
+* [Pivot Table](#pivot-table)
+* [Plugin](#plugin)
+* [Processing Pipeline](#processing-pipeline)
+* [ProcessingSource](#processingsource)
+* [Projection](#projection)
+* [SDK Driver](#sdk-driver)
+* [Simple Table](#simple-table)
+* [SourceDataCooker](#sourcedatacooker)
+* [SourceParser](#sourceparser)
+* [Special Columns](#special-columns)
+* [Table](#table)
+* [TableBuilder](#tablebuilder)
+* [Table Building Cycle](#table-building-cycle)
+* [TableCommand](#tablecommand)
+* [TableConfiguration](#tableconfiguration)
+* [VisibleDomainSensitiveProjection](#visibledomainsensitiveprojection)
+* [Windows Performance Analyzer](#windows-performance-analyzer)
+
+---
+
+## AboutInfo
+
+Exposes information about a plugin, such as its authors, copyright, and license. See [Adding About Information](./Using-the-SDK/Advanced/Adding-About-Information.md).
+
+## Column
+
+A ([ColumnConfiguration](#columnconfiguration), [Projection](#projection)) pair that defines data inside a [Table](#table).
+
+See also: [Special Columns](#special-columns)
+
+## ColumnConfiguration
+
+Information about a column of a [Table](#table). Contains the column's name, metadata, and [UIHints](#uihints).
+
+See also: [Projection](#projection).
+
+## ColumnRole
+
+Meta-information about a [Column](#column) that defines the Column's role in data presentation. For example, a Column that contains a `Timestamp` whose value indicates when an event occured relative to the start of a [DataSource](#datasource) may be marked as a "start time" Column.
+
+## CompositeDataCooker
+
+A [DataCooker](#datacooker) that receives input solely from other DataCookers.
+
+## CustomDataProcessor
+
+Component responsible for processing a [DataSource](#datasource). For example, a CustomDataProcessor may be responsible for parsing lines in a `.txt` file into `LineItem` objects that later get consumed by a [DataCooker](#datacooker) or [Table](#table).
+
+In most situations, a CustomDataProcessor will further delegate the responsibility of processing a DataSource to a [SourceParser](#sourceparser).
+
+A CustomDataProcessor is responsible for building any [Simple Tables](#simple-table) discovered by the [ProcessingSource](#processingsource) that created it.
+
+## DataCooker
+
+Component of a [Processing Pipeline](#processing-pipeline) that consumes data from one or more sources and optionally outputs new data for other components to consume. Conceptually, a DataCooker "cooks" data from one type to another.
+
+See also: [SourceDataCooker](#sourcedatacooker) and [CompositeDataCooker](#compositedatacooker).
+
+## DataSource
+
+An input to be processed by a [CustomDataProcessor](#customdataprocessor). In most situations, this is a `FileDataSource` that contains the full path to a file specified by a user. 
+
+## DynamicTable
+
+A [Table](#table) that is built outside of the standard [table building cycle](#table-building-cycle). DynamicTables are commonly built in response to a [TableCommand](#tablecommand) being invoked.
+
+## Pivot Column
+
+NOTE: (Not to be confused with the [Special Column](#special-columns) `PivotColumn`)
+
+A special type of [Column](#column) that should be pivoted about when its [Table](#table) is interpreted as a [Pivot Table](#pivot-table). Any Column that appears in a [TableConfiguration](#tableconfiguration) before the `PivotColumn` is a Pivot Column.
+
+## Pivot Table
+
+A representation of a [Table](#table) where certain [Columns](#column) are pivoted/grouped about. For example, consider this table with 5 rows:
+
+| State        | Zip Code | Population |
+|--------------|----------|------------|
+| Washington   | 98052    | 65,558     |
+| New York     | 10023    | 60,998     |
+| Washington   | 98101    | 13,877     |
+| Washington   | 98109    | 20,715     |
+| New York     | 10025    | 94,600     |
+
+If the "State" column above is a [Pivot Column](#pivot-column), the 5 rows would be grouped into the following Pivot Table:
+
+| State        | Zip Code | Population |
+|--------------|----------|------------|
+| > Washington |          |            |
+|              | 98052    | 65,558     |
+|              | 98101    | 13,877     |
+|              | 98109    | 20,715     |
+| > New York   |          |            |
+|              | 10023    | 60,998     |
+|              | 10025    | 94,600     |
+
+NOTE: the SDK has no understanding of Pivot Tables. Tables created by a plugin are purely "flat" tables - i.e. tables similar the first one above. It is up to programs like [Windows Performance Analyzer](#windows-performance-analyzer) to use pivot information in a [Table Configuration](#tableconfiguration) to present a plugin's Table as a Pivot Table.
+
+## Plugin
+
+A collection of one-or-more [ProcessingSources](#processingsource) that collectively create zero-or-more [Tables](#table) and consist of zero-or-more [DataCookers](#datacooker).
+
+## Processing Pipeline
+
+A collection of [DataCookers](#datacooker) and [SourceParsers](#sourceparser) that define a structured flow of data.
+
+## ProcessingSource
+
+An entrypoint for a [Plugin](#plugin). A ProcessingSource
+1. Declares a human-readable name and description
+2. Defines the [DataSource(s)](#datasource) it supports
+3. Creates the [CustomDataProcessor](#customdataprocessor) that will process instances of supported DataSources
+4. Advertises the [Table(s)](#table) that may be built in response to DataSources being processed
+
+## Projection
+
+A function that maps a row index for a [Table](#table) to a piece of data. Conceptually, a Projection is combined with a [ColumnConfiguration](#columnconfiguration) to complete define a Table's [Column](#column): the ColumnConfiguration defines the name and metadata about a Column, and its associated Projection defines the Column's data.
+
+## SDK Driver
+
+A program that utilizes the SDK and SDK plugins to process [Data Sources](#datasource) and present information to users.
+
+See also: [Windows Performance Analyzer](#windows-performance-analyzer).
+
+## Simple Table
+
+A [Table](#table) variant that cannot participate in a [Processing Pipeline](#processing-pipeline) and must be built by a [CustomDataProcessor](#customdataprocessor). Simple Tables should only be used if your plugin does not use [DataCookers](#datacooker). However, since in most data-processing situations it is recommended to use DataCookers to architect your data-processing, it is recommended to use only standard [Tables](#table).
+
+## SourceDataCooker
+
+A [DataCooker](#datacooker) that receives input from a specific [SourceParser](#sourceparser). A SourceDataCooker may also receive input from other DataCookers of the same SourceParser.
+
+## SourceParser
+
+An object that a [CustomDataProcessor](#customdataprocessor) typically tasks with parsing a [DataSource](#datasource) into individual records. The records that a SourceParser emits typically begin a [Processing Pipeline](#processing-pipeline), wherein [DataCookers](#datacooker) further process data to be consumed by [Tables](#table).  
+
+## Special Columns
+
+Columns that all [Tables](#table) may use in their [TableConfiguration](#tableconfiguration) and denote special behavior. These columns are
+* `PivotColumn`: a column that marks the end of columns which should be pivoted about. All columns in a Table that appear before this Special Column are interpreted as [Pivot Columns](#pivot-column)
+* `GraphColumn`: a column that marks the start of columns that can/should be graphed
+* `LeftFreezeColumn`: a column that marks the end of columns that should be frozen in GUIs
+* `RightFreezeColumn`: a column that marks the start of columns that should be frozen in GUIs
+
+## Table
+
+A collection of one-or-more columns that contain data. Each column of a Table must consist of the same number of rows.
+
+A Table may receive data from one-or-more [DataCookers](#datacooker). A Table is also responsible for "building itself" by having a static `Build` method interacts with a [TableBuilder](#tablebuilder).
+
+## TableBuilder
+
+The object used to concretely construct [Tables](#table) and [Simple Tables](#simple-table). When a [CustomDataProcessor](#customdataprocessor) is asked to build a Simple Table, or when a normal Table "builds itself," it will be given an instance of an `ITableBuilder` to add its [Columns](#column) and [TableConfigurations](#tableconfiguration) to.
+
+## Table Building Cycle
+
+The standard process used to construct [Tables](#table). This process involves
+1. A user specifying which [DataSource(s)](#datasource) to process
+2. [CustomDataProcessor(s)](#customdataprocessor) being given the selected DataSources to process
+3. [Simple Tables](#simple-table) being built by these CustomDataProcessor(s)
+4. [DataCooker(s)](#datacooker) further processing data produced by any [SourceParsers](#sourceparser) used by the CustomDataProcessor(s) referenced above
+5. [Tables](#table) "building themselves" from the data produced by these DataCookers. 
+
+## TableCommand
+
+An action that can be called on a [Table](#table). Concretely, a TableCommand is a `string => Func` key-value pair where the key is the TableCommand's name and the value is a function to be called when the TableCommand is invoked.
+
+A common use-case of TableCommands is creating [DynamicTables](#dynamictable)
+
+## TableConfiguration
+
+A pre-defined collection of properties for a [Table](#table). This includes, but is not limited to,
+* The order of [Columns](#column) in the Table
+* An initial filter to apply to the Table
+* [ColumnRoles](#columnrole) for Columns in the table
+
+## VisibleDomainSensitiveProjection
+
+A [Projection](#projection) that depends upon the visible subrange of values spanned by the Projection's [Table](#table)'s domain. For example, if a Table's domain is time-based (e.g. `Timestamp`-based), a VisibleDomainSensitiveProjection could be a Projection that reports the percent of time spent inside a method call _relative to the timerange currently visible to the user_.
+
+## Windows Performance Analyzer
+
+An [SDK Driver](#sdk-driver) that can display [Tables](#table) plugins create as [Pivot Tables](#pivot-table) and graph data in various formats.
diff --git a/documentation/Overview.md b/documentation/Overview.md
@@ -1,28 +1,32 @@
-# Abstract
+# Overview
 The Microsoft Performance Toolkit SDK allows developers to create "SDK plugins" that process and interpret data. 
 These plugins can be used by performance analysis applications that use the SDK runtime - such as [Windows Performance Analyzer](https://docs.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer) - to process data sources into structured, tabular data. Plugins may utilize the SDK's data-processing pipeline to both facilitate the creation of these tables and expose data that can be programmatically accessed by concurrently loaded plugins (even those without access to the originating plugin's source code).
 
 This folder contains instructions for developing SDK plugins and utilizing the SDK's various features.
 
+# Glossary
+
+For quick definitions/examples of terms and concepts, refer to the [Glossary](./Glossary.md). 
+
 # Requirements
 The following are required in order to develop an SDK plugin:
 * [NuGet](https://www.nuget.org/downloads)
 * [.NET Standard 2.0](https://dotnet.microsoft.com/download/visual-studio-sdks)
 * A text editor (for editing your source code)
 
-It is recommended to use [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) to develop an SDK plugin since it satisfies all three requirements. Future documentation assumes the use of Visual Studio, but the instructions may be adapted for other editors/IDEs.
+It is recommended to use [Visual Studio](https://visualstudio.microsoft.com/downloads/) to develop an SDK plugin since it satisfies all three requirements. Future documentation assumes the use of Visual Studio, but the instructions may be adapted for other editors/IDEs.
 
 # Getting the SDK
-The SDK is currently published as a NuGet package under the name [Microsoft.Performance.SDK](https://www.nuget.org/packages/Microsoft.Performance.SDK/). 
+The SDK is published as a NuGet package under the name [Microsoft.Performance.SDK](https://www.nuget.org/packages/Microsoft.Performance.SDK/). 
 Since it is hosted on [NuGet.org](https://www.nuget.org/), it can be added to a `csproj` with no additional configuration by using 
 the Visual Studio NuGet Package Manager, `dotnet.exe`, or `nuget.exe`.
 
-# Creating Your First Project
-Please see the [Creating your first project](Using-the-SDK/Creating-your-project.md)
+# Creating Your First Plugin
+Refer to [Creating your first plugin](Using-the-SDK/Creating-your-plugin.md)
 
 # Recommended Reading Order
 To best understand how the SDK works and how to develop SDK plugins, it is recommended to read documentation in the following order:
-1) [Architecture/Overview](./Architecture/Overview.md) to understand at a high level the various system the SDK provides
+1) [Architecture/Overview](./Architecture/Overview.md) to understand at a high level the various systems the SDK provides
 2) [Architecture/The Data Processing Pipeline](./Architecture/The-Data-Processing-Pipeline.md) to understand how to systematically process data that 
 can be used by tables
 3) [Using the SDK/Creating an SDK Plugin C# Project](Using-the-SDK/Creating-your-project.md) to get your developer environment ready to create an SDK plugin
diff --git a/documentation/Using-the-SDK/Creating-your-plugin.md b/documentation/Using-the-SDK/Creating-your-plugin.md
@@ -10,46 +10,24 @@ This document will cover:
 
 
 
-For simplicity, this section will assume you are using Visual Studio 2019. The instructions may be adapted for other editors / IDEs.
+For simplicity, this section will assume you are using Visual Studio. The instructions may be adapted for other editors / IDEs.
 
 <a name="reqs"></a>
 # Requirements
 
-1. [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/)
+1. [Visual Studio](https://visualstudio.microsoft.com/downloads/)
 2. [.NET SDK that supports .NET Standard 2.0](https://dotnet.microsoft.com/download/visual-studio-sdks)
    * [See .NET Standard 2.0 support options](https://docs.microsoft.com/en-us/dotnet/standard/net-standard)
 
-## Visual Studio 2019
-
-You can install Visual Studio 2019 from here: [https://visualstudio.microsoft.com/downloads/](https://visualstudio.microsoft.com/downloads/).
-Any edition is capable of creating an SDK plugin.
-
-1. Download the installer
-2. Execute the installer
-3. Make sure that the following features are selected:
-   * .NET Desktop Development (Make sure to select an appropriate .NET SDK for development option)
-4. Click "Install"
-5. You may have to restart your computer when installation finishes
-
-## .NET Standard 2.0
-
-If you installed Visual Studio 2019 based on the above instructions, then you are good to go. Otherwise,
-
-1. Execute your VS2019 installer, and choose to "Modify" the installation
-2. Make sure that the following features are selected:
-   * .NET Desktop Development (Should include an appropriate .NET SDK for .NET Standard 2.0)
-3. Click "Modify" to modify your installation
-4. You may need to restart your computer when modification finishes
-
 <a name="createproj"></a>
 # Creating Your Project
 
-1) Launch Visual Studio 2019
+1) Launch Visual Studio
 2) Click "Create new project"  
  ![VS2019_Create_New_Project.PNG](./.attachments/VS2019_CreateProject_Markup.png)
 3) Select .NET Standard on the left, and choose "Class Library (.NET Standard)." Make sure that you are using .NET Standard 2.0 
  ![VS2017_New_DotNetStandard_20_Project.PNG](./.attachments/VS2019_CreateProject_ClassLibrary_Markup.png)
-4) Give your project whatever name you want
+4) Name your project
 5) Click "Create"
 
 <a name="configure"></a>
@@ -75,10 +53,11 @@ Please see [Using the SDK/Installing WPA](./Installing-WPA.md) for more informat
 
 1) Right click your project and select "Properties"
 2) Select the "Debug" tab on the left
+   * In newer versions of Visual Studio, you may need to click "Open debug launch profiles UI"
 3) For "Launch", select "Executable"
 4) For the "Executable", place the path to the `wpa.exe` that you previously installed as part of the WPT
-  * Typically this might be: `C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\wpa.exe`
-5) For "Command line Arguments", add `-addsearchdir <bin folder for your plug-in>` (e.g. `-addsearchdir C:\MyAddIn\bin\Debug\netstandard2.1`)
+   * Typically this might be: `C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\wpa.exe`
+5) For "Command line Arguments", add `-addsearchdir <bin folder for your plugin>` (e.g. `-addsearchdir C:\MyAddIn\bin\Debug\netstandard2.1`)
 
 # Next Steps
 
diff --git a/documentation/Using-the-SDK/Installing-WPA.md b/documentation/Using-the-SDK/Installing-WPA.md
@@ -11,5 +11,5 @@ WPA is bundled as part of the [Windows Performance Toolkit](https://docs.microso
 - Download and run the setup program for the Windows Assessment and Deployment Kit.
 - Chose an installation path and follow installation insructions until you reach the "Select the features you want to install" screen.
   * Take note of the installation path as it will be used when debugging SDK plugin projects.
-- Make sure to select "Windows Performance Toolkit" from this screen.  ![ADK_Installation_Markup.png](/.attachments/ADK_Installation_Markup.png)
+- Make sure to select "Windows Performance Toolkit" from this screen.  ![ADK_Installation_Markup.png](./.attachments/ADK_Installation_Markup.png)
 - Click "Install and Close" when installation is complete.
